Errors
Response envelope, HTTP status codes and domain-specific error codes.
Response envelope
Successful responses:
{ "ok": true, "...": "...payload" }Error responses:
{ "ok": false, "error": "human readable message", "errorId": "abc123def456..." }errorId is auto-generated for every error response (4xx and 5xx) and
lets the support team locate the matching log entry. Quote it in any bug
report.
HTTP status codes
| Status | Meaning | Action |
|---|---|---|
| 200 | Success | — |
| 400 | Validation / business-rule error | Show error, do not retry. |
| 401 | Auth failure (key, signature, timestamp, replay) | Sync clock, verify key. |
| 403 | Forbidden (IP whitelist, permission, JWT-only endpoint) | Check permission set. |
| 404 | Resource not found (order id, transfer id, …) | Verify the id. |
| 409 | Conflict (idempotent retry, race, guard) | Inspect code — see below. |
| 429 | Rate limit exceeded | Wait for Retry-After, exponential back-off. |
| 500 | Internal error | Open a support ticket with errorId. |
| 503 | Transient failure (RPC down, etc.) | Retry with short exponential back-off. |
Domain-specific error codes
Some 4xx responses carry a code field alongside error — branch on it
programmatically:
code | Endpoint | Meaning | Client action |
|---|---|---|---|
OPEN_POSITION_LEVERAGE_GUARD | POST /v2/futures/leverage | Open position present; leverage change would shift liquidation price. | Resend with forceWithOpenPosition: true (only with explicit user intent). |
OPEN_POSITION_MARGIN_GUARD | POST /v2/futures/margin-type | Same guard, for margin-type changes. | Resend with forceWithOpenPosition: true. |
OPEN_POSITION_MARGIN_REJECT | POST /v2/futures/margin-type | Venue refused the margin-type switch even with forceWithOpenPosition: true (typically because the resulting margin would breach maintenance). | Close or reduce the position, then retry — or use POST /v2/futures/close-and-switch-margin to do both atomically. |
New codes will be added here as they ship. For unknown codes, fall back to
displaying error.