Error Codes

ZTDX exposes two API surfaces with two distinct error systems. Which one you get depends on the path you called, not on the credential you used.

1. Native surface — /api/v1/*

Errors are an HTTP status code plus a string error code. Two body shapes exist:

Handler-level errors (validation, business logic) use a flat body:

{ "error": "杠杆倍数必须在1-50之间", "code": "INVALID_LEVERAGE" }

Some handlers add an optional details object (e.g. the login endpoint's timestamp diagnostics).

Middleware / framework errors (authentication, generic failures) use the ApiResponse envelope:

{
  "success": false,
  "data": null,
  "error": { "code": "SIGNATURE_INVALID", "message": "Timestamp outside recv window" },
  "timestamp": 1778716800
}

Common string codes

HTTP	Code	Meaning
401	UNAUTHORIZED	Missing or malformed Authorization header
401	INVALID_TOKEN	JWT invalid or expired
401	INVALID_API_KEY	Unknown X-MBX-APIKEY
401	API_KEY_DISABLED	API key exists but is disabled
401	SIGNATURE_INVALID	HMAC signature mismatch, or timestamp outside the ±60s window; also invalid EIP-712 login signature
403	IP_NOT_ALLOWED	Caller IP not in the API key's whitelist
400	MISSING_SIGNATURE / MISSING_TIMESTAMP	JWT-auth trading request lacks the body EIP-712 signature / timestamp
400	TIMESTAMP_EXPIRED	EIP-712 body timestamp outside its validity window (orders: ±300 s; login: ±300 s)
400	INVALID_SIGNATURE_FORMAT	EIP-712 signature not parseable
400	INVALID_LEVERAGE	Leverage outside 1..max_leverage (default cap 50 when the symbol has no config)
400	INVALID_AMOUNT / INVALID_PRICE	Non-positive amount / price
400	PRICE_REQUIRED	Limit-type order without a price
400	TRIGGER_PRICE_REQUIRED	TP/SL order without trigger_price
400	NOTIONAL_TOO_SMALL	Order notional below min_order_size_usd (default $10)
400	INSUFFICIENT_BALANCE	Available balance below required margin
404	ORDER_NOT_FOUND / POSITION_NOT_FOUND	Referenced entity does not exist
500	INTERNAL_ERROR / DB_ERROR / DATABASE_ERROR	Server-side failure
502	SHARD_PROXY_ERROR	Symbol-shard forwarding failed

This list covers the codes you are most likely to encounter; individual endpoint pages document endpoint-specific codes (e.g. Account PnL).

2. Developer surface — /fapi/*

Binance-style errors: a JSON body with a negative integer code and a msg string.

{ "code": -4028, "msg": "Leverage 200 is not valid. Max: 125" }

The full table of /fapi error codes is maintained in USDT-Margined Error Codes.

Notes

• The two systems do not mix: /api/v1 never returns numeric Binance codes, and /fapi never returns the string-code bodies above.
• The leverage caps used in validation differ between surfaces when a symbol has no market config: /api/v1 falls back to 50, /fapi/v1/leverage falls back to 125.