Error Handling

Error codes, response format, and handling best practices

All API errors follow a consistent JSON format. Understanding error codes helps you build robust integrations.

Error Response Format

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {},
    "timestamp": "2025-01-01T00:00:00.000Z",
    "requestId": "abc-123-def"
  }
}

Field	Description
success	Always false for error responses
error.code	Machine-readable error code (use this for programmatic handling)
error.message	Human-readable description
error.details	Additional context (optional, varies by error type)
error.timestamp	ISO 8601 timestamp of the error
error.requestId	Unique request identifier for support inquiries

---

Authentication Errors

Code	HTTP	Description
AUTH_REQUIRED	401	No API key or token provided
AUTH_INVALID_API_KEY	401	The API key is not valid
AUTH_EXPIRED_API_KEY	401	The API key has expired
AUTH_REVOKED_API_KEY	401	The API key has been revoked
AUTH_IP_NOT_WHITELISTED	403	Request IP is not in the key's whitelist

Permission Errors

Code	HTTP	Description
PERMISSION_DENIED	403	The API key lacks the required permission
PERMISSION_TRADE_REQUIRED	403	TRADE permission is needed for this action
PERMISSION_READ_REQUIRED	403	READ permission is needed for this action

Rate Limit Errors

Code	HTTP	Description
RATE_LIMIT_EXCEEDED	429	General rate limit exceeded
RATE_LIMIT_SECOND	429	Per-second rate limit exceeded
RATE_LIMIT_MINUTE	429	Per-minute rate limit exceeded
RATE_LIMIT_DAY	429	Daily rate limit exceeded

Order Errors

Code	HTTP	Description
ORDER_NOT_FOUND	404	The specified order does not exist
ORDER_ALREADY_CLOSED	409	The order has already been closed
ORDER_INVALID_AMOUNT	400	Invalid order amount
ORDER_INVALID_POSITION	400	Invalid position value (must be over or under)
ORDER_INSUFFICIENT_BALANCE	422	Not enough balance to place the order
ORDER_TRADING_DISABLED	503	Trading is temporarily disabled
ORDER_PRODUCT_NOT_FOUND	404	The specified product does not exist
ORDER_MAX_ORDERS_REACHED	422	Maximum number of open orders reached
ORDER_FAILED	500	Order placement failed due to a server error
ORDER_CANCEL_FAILED	500	Order cancellation failed
ORDER_CLOSE_FAILED	500	Position close failed

Validation Errors

Code	HTTP	Description
VALIDATION_FAILED	400	Request body validation failed
VALIDATION_REQUIRED_FIELD	400	A required field is missing
VALIDATION_INVALID_FORMAT	400	A field has an invalid format

Validation errors include field-level details:

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Validation failed",
    "details": {
      "errors": [
        "epoch must be a number",
        "position must be one of: under, over"
      ]
    }
  }
}

Server Errors

Code	HTTP	Description
SERVER_ERROR	500	Internal server error
SERVER_MAINTENANCE	503	Service is under maintenance
SERVER_TIMEOUT	504	Request timed out

---

Best Practices

• Always check the success field before processing the response

• Use error.code for programmatic error handling, not HTTP status codes alone

• Implement retry logic for 429 (rate limit) and 5xx (server) errors

• Log requestId for debugging and support inquiries

• Do not retry 400, 401, 403, or 422 errors — fix the request first