Idempotency

Use idempotency when an interruption, timeout or lost response leaves doubt about whether a request was processed. The key identifies the same intent across attempts and prevents an accepted retry from repeating its effect.

The header is optional. Each endpoint page indicates whether it accepts Idempotency-Key.

When to use it

Send a key on creation requests and changes where repeating the effect would cause a duplicate or another unwanted update. The key does not replace the resource identifier, your system's reference or a result query.

The CLI and this documentation console do not retry writes automatically. Your system decides when to retry and must keep the same key while handling the same intent.

Send the key

Generate a unique key in your system and send it in the header:

Idempotency-Key: de305d54-75b4-431b-adb2-eb6b9e546014

UUID is accepted. The value must contain 1 to 255 visible ASCII characters, without spaces or control characters. Do not include credentials, tax IDs or other personal data in the key.

Store the key with its corresponding request or action. The console shows the field under Headers when the endpoint accepts idempotency. The value remains only in the tab's memory, associated with the operation and account. The console does not create or replace the key between attempts.

Retry the request

If the response is lost, retry the same method, path, body and Idempotency-Key. A compatible retry returns the preserved result instead of executing the request again.

Validation failures returned before execution are not stored. 4xx responses are not preserved either. Correct the request before trying again and keep the same key only when the intent remains the same.

If the idempotency store is unavailable, a request with the header receives a 503 before the action runs. This response is not preserved and can be retried with the same key. Without the header, the request follows the endpoint's normal flow.

Reusing the key with a different method, path or content returns 422. Use the key only with the request that represents the original intent.

Interpret the result

When a response comes from a preserved retry, the API sends:

Idempotency-Replayed: true

The status and body remain identical to the stored result. A 202 response still means processing is pending. Store the returned identifier and track the same resource; replay does not turn a pending result into completion.

Successful responses and 5xx failures that occur after admission are preserved. Retrying a key that received 500 may therefore return the same error. Query the resource and reconcile the effect before creating another key.

A 409 IDEMPOTENCY_RESULT_UNKNOWN response means the endpoint may have completed, but its response could not be preserved. Query the resource before retrying. If the response contains Location, start with that address. After reconciliation, a retry of the same intent keeps the same key; never replace the key to bypass this state.

Retention and reconciliation

The result remains available for 24 hours. After that period, the same key may start another processing attempt. Do not use expiration to resolve an uncertain financial operation.

Before changing the key, query the resource by its identifier, use your system's reference when a filter is available and process received webhooks. Send a new intent only after confirming the current state.