Idempotency And Concurrency
Use Idempotency-Key to retry a POST without repeating its effect. Use
If-Match where an endpoint requires a precondition on the current resource
version. The endpoint reference lists whether each header is required.
Idempotency
The edge caches successful responses for eligible POST requests for 24 hours. Some operations require the header; others generate an internal key or accept a body or query key instead. Omitting the header skips the edge response cache and does not by itself make a retry safe. Follow the operation's documented requirements.
Credentials are never replayed. Operations that issue one bypass the cache
entirely, so each call issues a new credential: POST /oauth/token,
service-account secret rotation, action tokens, KYC access tokens and client
verification sessions, and invitation acceptance. Service-account creation and
provisioning are deduplicated instead: a retry with the same key and body
returns the created account again, without client_secret. The secret appears
only in the first response.
- Choose a distinct key for each logical request, at most 128 characters long.
- Reuse the key and the same body when retrying that request.
- The key is scoped to the HTTP method, the concrete URL path and the
authenticated caller: its principal, tenant boundary and subject. The only
POSTs that accept no bearer token,
POST /oauth/tokenand invitation acceptance, bypass the cache. The edge hashes the body, not query parameters; keep query parameters unchanged when retrying. - A completed replay returns the original status and body while the key is
retained. A replayed service-account creation omits
client_secret. - Reusing a key with a different body returns
409 idempotency_conflict. Concurrent duplicates wait for the original transaction and then replay its result.
For example, creating a client requires a key:
See Create client for the body. If a financial operation later fails asynchronously, retrying its original acceptance with the same key still returns that acceptance. A new execution attempt needs a new key after you have inspected the failed operation.
Concurrency Control
Use the current resource ETag on operations whose reference lists If-Match.
For example, Update client requires it:
A mismatched precondition returns 412 precondition_failed. Re-read the
resource, reconcile the intended change, and retry with its current ETag.
A missing required header can return 400.
ETags and preconditions are endpoint-specific. Client suspension and financial
operation cancellation, for example, do not accept an If-Match precondition.
Do not assume that every PATCH or lifecycle action performs an ETag comparison.