Idempotency-Key header

Use Idempotency-Key to retry a request without creating a duplicate operation. The guarantee is exactly-once acceptance: within the 3-hour retention window, retries with the same key and identical request must resolve to the original operation, even if you lost its response. For retry strategy, see Idempotency.

Request header

Workspace- and organization-scoped mutations support the response replay described below. User-only and unscoped unauthenticated operations and streams bypass it. Operations with a separate replay contract define their behavior in their reference page.

Omitting the header or sending an empty value processes the request normally without deduplication. On endpoints that declare this header, a key longer than 255 characters returns 422 with code E01001 ValidationError.

Keys are scoped to your workspace, or to your organization on organization-level endpoints, and retained for roughly 3 hours. After the retention window, a reused key is processed as a fresh request.

Response semantics

A replayed response is byte-for-byte the original (same status code, same body), distinguished only by the extra header:

HTTP/1.1 202 Accepted
Idempotency-Replay: true

"Identical request" covers the method, endpoint, path and query parameters, and the raw request body; a difference in these values, including JSON whitespace, triggers E01005. Multipart uploads compare part names, filenames, and contents; boundaries and part ordering do not affect replay. Both 409 errors come wrapped in the standard error envelope.

Retained responses can include 4xx rejections. Use a new key when correcting a request: if its rejection was retained, an unchanged retry replays it, and a changed request returns 409 E01005 IdempotencyKeyReuse.

Retry a timeout or 5xx with bounded backoff using the same key and identical request within three hours. The exactly-once acceptance guarantee applies even when the original response was lost. E01033 IdempotencyUnavailable means this attempt did not execute; it does not describe the outcome of an earlier attempt. Keep the key on every retry.

For a message send, exactly-once acceptance means one accepted send across matching retries. Check the message status to confirm delivery. After three hours, check the original operation’s outcome before submitting again: an expired key or a new key can create another operation.

SDK behavior

The official SDKs attach an auto-generated UUID Idempotency-Key to every mutating request, generated once per logical call and reused across all retry attempts of that call. You can supply your own key per call (idempotencyKey in TypeScript, option.WithIdempotencyKey in Go, idempotency_key in Python, new RequestOptions(idempotencyKey: ...) in PHP) when one logical operation spans multiple SDK calls. To detect a replay, read the Idempotency-Replay response header through each SDK's transport-metadata accessor: .withResponse() in TypeScript, option.WithResponseInto in Go, and with_raw_response in Python.

Related

• Idempotency concepts: retry strategy, key design, and replay limits
• Error responses: the envelope wrapping E01004 and E01005
• Email messages: the send endpoint, the most common place to use a key
• SDK concepts: automatic key generation and retries