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/token and 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:

POST /clients
Authorization: Bearer <access_token>
Idempotency-Key: client-create-001
Content-Type: application/json

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:

PATCH /clients/<client_id>
Authorization: Bearer <access_token>
If-Match: <current ETag returned by GET>
Content-Type: application/json

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.