Errors & Retries

The API fails in deliberately boring, uniform ways: one problem shape, stable machine codes, a correlation id on every response — success or failure — and idempotency where retries matter. This page is the contract your error paths should be written against.

The problem shape

Every error response is an RFC 9457 problem document, sent as application/problem+json; charset=utf-8:

{
  "title": "The request could not be completed.",
  "status": 409,
  "detail": "Use the error code and correlation ID when contacting support.",
  "code": "price_above_maximum",
  "correlationId": "0198e001a2b37c4d8e9f0a1b2c3d4e5f",
  "quotedTotal": 61.20,
  "currency": "USD",
  "maximumTotal": 60.00,
  "message": "The price is now above the most you agreed to pay."
}

The response language

message, title, detail and the messages in errors are written in the language you ask for with the X-Language header — or, without it, your Accept-Language — and in English otherwise. Xegora writes en, ar, de, es, fa, fr, hi, pt, ru, tr and zh. The response says which it used in Content-Language, with Vary: X-Language, Accept-Language. Codes, correlation ids and facts are the same in every language, and successful responses are not translated.

Error responses are never cacheable (Cache-Control: no-store).

Correlation ids

Send X-Correlation-Id with a request to have your own id carried through our logs and audit records: it is kept when it is 1–128 characters of ASCII letters, digits, ., _, : and -, and replaced by an id of ours (32 lowercase hex characters) otherwise — so a value with spaces, a comma, or anything else is never echoed back.

Every response carries the id in the X-Correlation-Id response header — successes and problem documents alike, on every path: a refusal from the rate limiter, from authentication, from the access-standing check, or from an unexpected fault. A problem document carries the same value again in its correlationId, so the header and the body always agree and either one is safe to read.

Status codes and what to do

Codes

Every code the API answers with. Branch on these; keep clients tolerant of codes added later.

Rate limiting

Two budgets apply to a workspace, each a fixed one-minute window with no queueing, shared by all of the workspace's keys:

• The API budget: 120 requests per minute per workspace, for every endpoint except catalog images. GET /api/v1/workspace reports it as rateLimit.requestsPerMinute.
• The catalog image budget: 300 requests per minute per workspace, for GET /api/v1/catalog-product-images/… only, so drawing product pictures never spends what your orders need.

Before a key is checked, every request is also counted by its source address: a per-minute budget and a cap on concurrent requests per address. All workspaces and keys calling from one egress address share it. A request without a valid key is counted by its address.

Every admitted response says the budget it was counted against and what is left of it in the current window:

RateLimit-Limit: 120
RateLimit-Remaining: 87

A refused request receives 429 with code: "rate_limited" and a Retry-After header — whole seconds, as the limiter reports them: 60 when a per-minute budget is spent (the window's length — your budget may come back sooner, never later) and 1 when the per-address concurrency cap refused it. A refusal of a per-minute budget also carries RateLimit-Limit (120, 300, or the per-address budget), RateLimit-Remaining: 0 and RateLimit-Reset (the same seconds as Retry-After).

• Spread scheduled jobs (catalog walks, reconciliation sweeps) across the minute instead of firing at :00, and pace them by RateLimit-Remaining.
• On 429, sleep the advertised Retry-After, then resume; add jitter if several workers share the workspace.
• Sustained 429s mean your architecture is polling where it should be consuming webhooks.

Retry rules that keep money safe

1. Idempotent mutations, always keyed. POST /orders and POST /orders/{id}/fulfillment require an Idempotency-Key, and POST /withdrawals takes one — send it. Retry timeouts/5xx with the same key and you can never double-purchase, double-withdraw or lose a response — including a one-call order that names its item: the retry is answered by the order the key already placed, and nothing is priced again.
2. The scary case — a timeout on POST /orders — is already solved. You don't know whether the order was created; resending with the same key returns the existing order if it was, creates it if it wasn't. Never "check first, then maybe resend" — just resend with the key.
3. A reveal's key replays for 15 minutes. Retry a timed-out reveal under the same key within 15 minutes and you receive the stored response without spending a reveal; after that the key answers 409 fulfillment_replay_expired. A reveal key sent for a different order answers 409 idempotency_conflict — one key per intended reveal.
4. Reads are safe to retry (GETs are side-effect free). Use capped exponential backoff with jitter: e.g. 1s, 2s, 4s, 8s (±20%), give up after ~5 attempts into your dead-letter/alerting path.
5. Never retry 4xx other than 429 and 409 concurrent_update (resend it under the same key) — every other outcome is deterministic until you change the request or its circumstances (fund the wallet, quote again).
6. On 409 idempotency_conflict, look the order up before you reach for another key. GET /orders?clientReference=<your reference> is authoritative: a new key for a purchase that was in fact already placed buys it a second time. Only use a fresh key once you have seen that no order of yours matches. (A one-call retry of an order whose receipt kept no record of the request — one placed before this release, or one placed from a quote — is still answered when the order itself matches the retry: see Orders.)
7. Withdrawal requests sent without a key cannot be told apart: on a timeout, read before retrying — GET /withdrawals/page?status=Requested — and only resend if your request is genuinely absent. Sending an Idempotency-Key removes the problem.

Timeouts and connections

• A client timeout of 10–15 s covers every endpoint comfortably; most respond in tens of milliseconds.
• Reuse HTTPS connections (keep-alive); per-request TLS handshakes are wasted latency.
• Keep the number of concurrent requests from one address modest: the per-address concurrency cap refuses the excess with 429 and Retry-After: 1.
• Treat DNS/TLS/socket errors exactly like 5xx: retry idempotently with backoff.

An error-handling skeleton

response = send(request with Idempotency-Key where applicable)

switch response.status:
  2xx      → done
  429      → sleep(Retry-After); retry (same key)
  503      → sleep(Retry-After); retry (same key)
  5xx / IO → backoff(attempt); retry (same key); after N attempts → dead-letter + alert
  409      → domain outcome → dedicated handler (re-quote / wait / adjust); concurrent_update → retry (same key)
  422      → domain outcome → change the request or stop
  404      → authoritative absence → reconcile local state
  400      → bug in request construction → log correlationId, fail fast, alert
  403      → api_access_inactive → billing/standing alert (reads may still work)
             ip_not_allowed / forbidden → credentials, scopes or egress misconfigured → alert operations
  401      → credentials misconfigured → alert operations

Wire correlationId through every branch — future-you, and our support team, will thank you.