Trading API
Errors and retries
Every error code the API returns, what each one means, and when a retry is safe.
Branch on error.code, never on the message text: codes are stable and messages are not.
| Code | HTTP | What it means and what to do |
|---|---|---|
MISSING_API_KEY | 401 | No key in the request. Send X-API-Key or Authorization: Bearer. |
INVALID_API_KEY | 401 | Malformed or not recognised. Check you are on the right environment. |
API_KEY_REVOKED | 401 | That key was revoked in the app. Other keys on the account still work. |
API_KEY_EXPIRED | 401 | That key has passed its expiry. Issue a new one. |
ACCOUNT_SUSPENDED, ACCOUNT_DISABLED | 403 | The account's status was set by Cardiv. Resting orders are unaffected; contact support. |
SESSION_REQUIRED | 403 | A key was used on /api/v1/api-keys. Manage keys in the app. |
PAIR_NOT_ALLOWED | 403 | The pair is not on your account. Check limits.allowedPairs. |
INVALID_CLIENT_ORDER_ID | 400 | The clientOrderId is missing your account's prefix or is over 120 characters. error.expectedPrefix carries the required value. |
VALIDATION_ERROR | 400 | Malformed request, or the order is below the minimum size. Not retryable unchanged. |
INVALID_PRICE_TICK | 400 | The price is off the pair's priceTick. |
INSUFFICIENT_BALANCE | 400 | Nothing spendable in the token this order commits: none at all, or all of it already locked to resting orders. Remember the fee comes out of the same token. |
PREAPPROVAL_REQUIRED | 400 | Your wallet cannot yet receive the token this order would bring in. |
LEDGER_COMMAND_REJECTED | 400 | The command was refused, and this code also covers a submission timeout. Check GET /orders/{orderId} before you retry. |
MAX_OPEN_ORDERS | 429 | You are at your open order cap. Cancel something, or ask for a higher cap. |
RATE_LIMITED | 429 | Past your per-minute limit. The body carries the limit. Back off. |
CACHE_EXPIRED | 410 | Past the five minute prepared-transaction deadline. Prepare again. |
CONTRACT_NOT_FOUND | 404 | A stale identifier, an order that is not yours, or a placement that has not settled yet. Re-read GET /orders. |
ORDER_ALREADY_FILLED, ORDER_ALREADY_CANCELLED | 400 | The order ended before your cancellation was processed. |
MAX_ACTIVE_KEYS | 409 | Issuing a key at the five-key cap, in the app. Revoke one first. |
AUTH_NOT_CONFIGURED | 503 | Keys are not enabled on this environment. Write to support. |
Retry policy
- 4xx is not retryable unchanged. Fix the request first.
- Prepare, on 5xx or timeout, is retryable with the same
clientOrderId. Placement is idempotent on that value, so a retry cannot double your exposure. - Submission, on 5xx or timeout, is never retried blind. Check
GET /orders/{orderId}first: the transaction may have committed despite the failed response, and re-preparing an order that is already resting doubles your position.
One known limitation
Calden currently collapses submission failures into a single generic 502, so a degraded network and a rejected signature look the same from the response alone. On an unexplained 502, check GET /orders/{orderId}, then contact Cardiv support with the correlationId and ask for the server-side cause.
Need help
Write to support@wolfedgelabs.com and include your party ID.