Error Responses

Errors are returned either for the entire request or for an individual item in a batched exchange action. Clients must handle both forms.

Request Errors

A rejected request normally returns a non-200 HTTP status and a machine-readable code:

{
  "error": "Missing 'action.type' field",
  "code": "MISSING_FIELD",
  "field": "action.type",
  "timestamp": 1785254400000
}

field, intentId, and retryAfter are included only when relevant. Some read endpoints return the older { "error": "..." } shape without a code. Error messages can change; use code for program logic when it is present.

Error Codes

Error source	Error code	Meaning
Request	`UNKNOWN_TYPE`	The action or request type is not supported
Request	`MISSING_FIELD`	A required field is missing
Request	`INVALID_FORMAT`	A field has the wrong type or format
Request	`INVALID_PRECISION`	A numeric value has too many decimal places
Request	`NEGATIVE_VALUE`	A value that must be non-negative is negative
Request	`VALIDATION_FAILED`	The request failed another validation rule
Signing	`INVALID_SIGNATURE`	Signature verification failed
Signing	`NONCE_ALREADY_USED`	The nonce was already processed and is not an exact retry
Authorization	`UNAUTHORIZED`	The signer is not authorized for the requested action
Order risk	`VENUE_POSITION_LIMIT`	The order exceeds the venue position limit
Order risk	`WALLET_RISK_LIMIT`	The protocol wallet is above its venue-risk limit
Account	`MARGIN_VIOLATION`	The account has insufficient margin
Account	`INSUFFICIENT_BALANCE`	The account has insufficient balance
State	`INVARIANT_VIOLATION`	The action violates a protocol business rule
State	`INVALID_STATE`	The requested state transition is no longer valid
State	`NOT_FOUND`	The referenced asset, market, or order was not found
Venue	`ORDER_REJECTED`	The execution venue rejected the order
System	`BACKPRESSURE`	The service is under load; retry after the supplied delay
System	`CIRCUIT_BREAKER_OPEN`	Trading is paused by a circuit breaker
System	`SERVICE_UNAVAILABLE`	A required service is temporarily unavailable
System	`INTERNAL_ERROR`	The server encountered an unexpected error

Batched Action Errors

Order, cancel, and modify results normally contain one status for each item in the request. An individual item can fail even when the HTTP status is 200 and the top-level status is ok:

{
  "status": "ok",
  "response": {
    "type": "order",
    "data": {
      "statuses": [{ "resting": { "oid": "0x1a2b..." } }, { "error": "Insufficient margin" }]
    }
  }
}

Action source	Result	Meaning
Order	`resting` or `filled`	The order was accepted or filled
Order	`pending`	Venue confirmation has not completed
Order	`pendingTrigger`	A local trigger order is waiting for its trigger
Order	`pendingParentFill`	A TP/SL child is waiting for its parent to fill
Order	`prefunding`	A spot buy is waiting for protocol prefunding
Order	`error`	The order was rejected
Cancel	`success`	The order was canceled
Cancel/modify	`error`	The requested operation was not completed

Inspect every item in response.data.statuses. When present, metadata.results also contains the Notional order ID and the corresponding status. Some errors apply to the whole payload, such as an invalid signature, a reused nonce, or malformed batch data. These are returned once as a request error rather than once per item. A batching client must therefore support both a single request error and an array containing item-level errors.

HTTP Statuses

Status	Meaning
`400`	The request is malformed or incomplete
`401`	Authentication or authorization failed
`422`	The request conflicts with a semantic rule
`429`	The endpoint is temporarily rate limited
`500`	The server encountered an unexpected error
`503`	The service is busy, paused, or unavailable

For 429 and 503, respect the Retry-After header when it is present. Do not retry other 4xx responses without changing the request. After a timeout, disconnect, or 500, check the current account and order state before submitting a new signed action. For orders, use Open Orders and Historical Orders. /exchange responses can include X-Request-Id, X-Client-Request-Id, and X-Transaction-Id. Record these values when reporting an unexpected failure.

Start Here

Info

Exchange

WebSocket

Request Errors

Error Codes

Batched Action Errors

HTTP Statuses

​Request Errors

​Error Codes

​Batched Action Errors

​HTTP Statuses

Request Errors

Error Codes

Batched Action Errors

HTTP Statuses