Errors are returned with a non-2xx HTTP status and a JSON body. The response field is human-readable; use the HTTP status and the error code for programmatic handling.
Response shape
code
{
"status": "err",
"response": "Insufficient margin to place order"
}HTTP status
| Status | Meaning | Retry? |
|---|---|---|
| 400 | Invalid request or validation error | No |
| 401 | Missing or invalid signature | No |
| 403 | Account not permitted | No |
| 404 | Unknown route or asset | No |
| 409 | Nonce conflict or duplicate order | Sometimes |
| 429 | Rate limit exceeded | Yes, with backoff |
| 500 | Internal error | Yes, with backoff |
| 503 | Temporary unavailability | Yes, with backoff |
Exchange errors
| Error | Cause | Fix |
|---|---|---|
Invalid signature | Wrong domain, hash, or signer | Re-sign with the correct chain ID |
Nonce too low | Reused nonce | Increment the nonce |
Nonce too high | Clock skew > 10s | Sync the system clock |
Insufficient margin | Not enough collateral | Reduce size or add margin |
Invalid price | Tick size violation | Round to the market tick |
Invalid size | Lot size violation | Round to the lot size |
Reduce only order would increase position | Wrong side or size | Check the position |
Order not found | Canceled or filled | Refresh open orders |
Action already expired | expiresAfter in the past | Generate a new timestamp |
Market halted | Governance or deployer halt | Wait for the market to resume |
Do not blind-retry writes
A timeout does not mean the action failed. Before retrying a signed action, query the order by cloid or oid. Retrying an order without a cloid can create a duplicate.
Retry policy
- 429: read
Retry-After, wait, then retry with jitter. - 500 / 503: retry up to 3 times with exponential backoff.
- 409: resolve the nonce or duplicate state before retrying.
- 400 / 401 / 403: fix the request; do not retry.
Idempotency
Use a unique cloid for every order. If the response is lost, orderStatus by cloid tells you whether the order exists. For cancels, a “not found” result is safe to treat as success.