Idempotency

Some write operations can be retried safely without creating duplicate side effects. On idempotency-compatible routes, send an optional client-generated idempotency key. If the API has already processed an identical request with the same key, it replays the original response instead of running the operation again.

Identifying compatible routes

Not every endpoint supports idempotency. In the API reference, look for operations marked with an Idempotent badge.

Those routes also document the idempotency headers in their operation details:

x-corma-idempotency-key — optional request header
x-corma-idempotency-replayed — response header (present only when a cached response is replayed)

If an operation has no Idempotent badge and does not list these headers, idempotency does not apply and every call is processed independently.

Request header

Header	Required	Description
`x-corma-idempotency-key`	No	Client-generated string (min. 1 character). Reuse the same value when retrying the same request.

If the header is omitted, the route behaves as a normal write: every call is processed independently.

Example:

POST /v1/example HTTP/1.1
x-corma-api-key: API_KEY_ID:API_KEY_SECRET
x-corma-idempotency-key: my-operation-2024-06-02
Content-Type: application/json

{ /* request body */ }

Choose keys that are unique per logical operation in your system (for example a UUID, or a stable business identifier such as onboard-{userId}-{date}).

How matching works

When an idempotency key is present and the request is authenticated, the API computes a fingerprint from:

HTTP method
Request path
JSON request body
API key ID (from x-corma-api-key)

The first successful response for a given key is stored for 24 hours together with that fingerprint.

Situation	Behavior
Same key and same fingerprint	Cached response is returned (see replay header below).
Same key but different fingerprint (method, path, body, or API key changed)	`400 Bad Request` — `Idempotency fingerprint mismatch`
New key	Request is processed normally; response is cached under the new key.

This means you can safely retry network failures or timeouts: resend the exact same request with the same idempotency key.

Replay response header

When a response is served from the idempotency cache, the API adds:

Header	Description
`x-corma-idempotency-replayed`	Set to the idempotency key that was replayed.

The response status code and body match the original successful response.

Example (replayed response):

HTTP/1.1 200 OK
x-corma-idempotency-replayed: my-operation-2024-06-02
Content-Type: application/json

{ /* same body as the first successful call */ }

If this header is absent, the response was produced by a fresh execution of the route handler.

Best practices

Generate one idempotency key per logical operation and keep it stable across retries.
Do not reuse a key for different payloads or endpoints — you will get a fingerprint mismatch.
Do not reuse a key across different API keys in the same workspace unless you intend those calls to be treated as the same operation (the fingerprint includes the API key ID).
Store the key client-side until the operation succeeds or you abandon the retry window (cache entries expire after 24 hours).

Pagination

Mutation payloads