Retries and idempotency (all eight SDKs)

The generated clients send one request and report what came back. For an API that moves money, a partner also needs to survive a timeout, a rate limit and a request that is still running. Every SDK therefore ships a small, opt-in retry layer with the same behaviour. It works at the HTTP transport level (before a response is turned into a model), so it also sees the 202 that means "still running", which the generated code would read as a success.

What counts as safe to repeat

A request is repeatable when it is a GET/HEAD, or when it carries an Idempotency-Key header. The API requires that header on the 17 operations that create or change money, orders or amendments (orders of every product, payment and fulfillment retries, cancellations, updates, amendments, wallet transfers, eSIM provisioning); the server then guarantees that repeating the request with the same key and the same body never does the work twice. Any other POST (a quote, for example) is not repeatable.

The same request is sent again byte for byte: the same method, URL, headers (so the same Idempotency-Key) and body.

When it retries

Situation Repeatable request Not repeatable (POST without a key)
Network error or timeout before a response retry surface the error
429 retry, wait Retry-After retry, wait Retry-After (the request was refused before it ran)
502, 503, 504 retry surface the response
Response with body code 12002 (IDEMPOTENCY_KEY_IN_PROGRESS), status 202 or 409 retry, wait Retry-After (2 s if absent), same key and body not applicable
500 never (the API says to check existing orders and call support) never
409 with 12001 or 12000, and any other 4xx never never

After the last allowed attempt, the last response (or error) is returned unchanged, so the caller sees exactly what the server said.

Waiting

Options and defaults (names follow each language's conventions)

Option Default Meaning
maxRetries 3 Retries after the first attempt for network errors, 429, 502/503/504 (so at most 4 attempts)
baseDelay 500 ms First backoff step
maxDelay 30 s Upper bound of any wait, including Retry-After
inProgressRetries 10 Retries for 12002
onRetry none Optional callback (attempt, reason, delay) for logging

Using it

Every SDK exposes the same two things (see its README for the exact names):

  1. Enable retries on the client you already use: one call that wraps the HTTP layer.
  2. newIdempotencyKey(): a fresh random UUID (version 4) to pass as the Idempotency-Key of one purchase intent. Make it once, before the first attempt, and keep it for that purchase. Never reuse a key for a different purchase, and never "get a new key" to get around an error: after a timeout or 5xx repeat the same key and body.