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.
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.
| 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.
- Delay before retry n (1-based):
random(0, min(maxDelay, baseDelay * 2^(n-1)))(full jitter), but never less than the server'sRetry-Afterwhen there is one.Retry-Afteris either whole seconds or an HTTP date; an invalid or negative value is ignored. The result is capped atmaxDelay. -
12002has its own budget (inProgressRetries) because an order can take longer than a few seconds; each wait is the server'sRetry-After, not the exponential delay.
| 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 |
Every SDK exposes the same two things (see its README for the exact names):
- Enable retries on the client you already use: one call that wraps the HTTP layer.
-
newIdempotencyKey(): a fresh random UUID (version 4) to pass as theIdempotency-Keyof 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 or5xxrepeat the same key and body.