Errors & rate limits

The envelope

{ "error": { "code": 4001, "slug": "insufficient_funds",
             "message": "Required 1300000 SUN, available 420000 SUN",
             "field": null, "retryable": true,
             "details": { "required_sun": 1300000, "available_sun": 420000 } },
  "request_id": "req_01J9Z5P8T3WQ7X" }

Branch on slug or code, never on the HTTP status alone — several distinct conditions share a status (409 covers both an idempotency conflict and an order that cannot be reclaimed, and they call for opposite reactions). Unknown codes will appear: treat one you do not recognise as its status class (4xx “my fault, do not retry blindly”, 5xx “their fault, retry with backoff”). Do not fail closed on an unrecognised slug.

Ranges: 1000–1099 auth/credentials · 1100–1199 rate limiting and quotas · 2000–2099 request validation · 3000–3099 business state · 4000–4099 money · 5000–5099 supply · 9000–9099 internal.

Codes

Validation codes (2000–2099) are all retryable: false and carry field where a single field is at fault; fix the request, retrying it unchanged fails identically.

The supply guarantee: a 503 from order creation never costs you money: either nothing was charged (5001, 5004), or the order ends failed and the charge is credited back (5007). Retrying with the same client_order_id is safe. Where a charge happened and delivery then failed (5002), the order exists, is terminal, and the money is credited back: read it and start a new order rather than retrying the old id.

Retry policy

Retry on 429, 5xx, and on 4001/4002/4004 after fixing the cause. Do not retry any 400, 401, 403, 404, or a 409 other than 4004 — those need a changed request. Always send client_order_id on order creation so every retry is free of double-purchase risk. Exponential backoff starting at 250 ms with full jitter, delay capped at 30 s, give up after roughly 60 s of wall-clock time rather than a fixed attempt count — then read the order by its client id to find out what happened. Honour Retry-After whenever present; it overrides your own schedule.

HTTP status map

200 success, also an idempotent replay of a create and a reclaim that had already happened · 201 a new object was created · 202 accepted for asynchronous processing (batches, and a reclaim whose hash had not landed yet — nothing delivered) · 204 success with no body (deletes, cancels) · 400 malformed or invalid request · 401 credentials missing, wrong, stale or from a disallowed IP · 402 not enough money · 403 authenticated but not permitted · 404 no such object for this account · 409 conflicts with current state, including idempotency conflicts · 422 well-formed but semantically impossible · 429 rate or quota limit · 500 unhandled internal failure · 501 contract-defined but not deployed · 503 temporarily unable to serve, fail-secure on creates · 504 upstream timeout, outcome unknown.

Rate limits

Per API key, and additionally per source IP. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds). Exceeding a limit returns HTTP 429 with 1100 rate_limited and a Retry-After header.

Default budgets (per key, per second). The dashboard shows the budgets in force for your key; higher limits on request:

Next steps

• Authenticationthe 1xxx codes come from here; sign each attempt afresh.
• Webhooksorder.failed carries the same failure.code and slug.
• Orders referencewhich endpoint answers which code.