Stop the same request from being processed twice. Requests that repeat an identifier within a set time are rejected.
Overview
An Idempotency Policy stops duplicate requests from reaching the backing resource. Each request is identified by a header value, the full payload, or a set of payload fields. If a request arrives with the same identifier as an earlier one within the idempotency window, the gateway rejects it with 409 Conflict. Use it when a client may retry a call that creates or changes data, such as placing an order or taking a payment.
The policy applies only to POST and PATCH requests. Requests that use any other method pass through without a check.
Field Reference
Field | Description |
|---|---|
Policy Name * | A descriptive name for the API policy. |
Tags | Labels to organize and filter the policy. |
Identifier source * | Choose what identifies a request as a duplicate: Request Header, Full Payload, or Payload Fields. Default: Request Header. |
Header name | Shown when the identifier source is Request Header. The request header that contains the idempotency identifier. Default: |
Identifier fields * | Shown when the identifier source is Payload Fields. The JSON payload fields that identify the request, for example |
Duration (Idempotency window) | How long requests with the same identifier are rejected. Pick a unit: Seconds, Minutes, Hours, or Days. Minimum: 1. Default: 10 minutes. |
Identifier Sources
Request Header — the value of the header named in Header name. The client sends a new value with each new request and the same value when it retries. If the header is missing, the request is rejected with 400.
Full Payload — the whole JSON body. Two requests with the same body are duplicates, even if their keys are in a different order. A request with no body is rejected with 400.
Payload Fields — the values of the fields listed in Identifier fields. Use dot notation for nested fields, for example
payment.transactionId. Every listed field must be present. If one is missing, the request is rejected with 400.
How It Works
Method checked — the policy runs only for POST and PATCH requests. Other requests continue unchanged.
Identifier resolved — the gateway reads the identifier from the source you chose. If it can't, the request is rejected with 400.
Duplicate check — the gateway checks whether the same identifier was already received for this API from this client within the idempotency window.
New request continues — a new identifier is recorded for the length of the window, and the request goes on to the backing resource.
Duplicate rejected — a repeated identifier within the window is rejected with 409. The backing resource is not invoked, and the first response is not returned again.
Client errors release the identifier — if the backing resource returns a 4xx response, the identifier is released. The client can fix the request and retry with the same identifier. After any other response, including a 5xx error, the identifier stays recorded until the window ends.
Status Codes
Status | When |
|---|---|
409 Conflict | A request with the same identifier was already received within the idempotency window. Message: "Duplicate request: a request with the same idempotency key already processed". |
400 Bad Request | The identifier is missing or can't be read: the header is absent, the request has no body, or a listed field is missing. Message: "Idempotency key is missing or could not be resolved". |
500 Internal Server Error | The policy is not configured correctly ("Idempotency policy is not configured correctly"), or the duplicate check could not run. |
Attaching the Policy
Attach an Idempotency Policy from the policy settings of an API or an API Group. It can't be attached to an access profile, and an API or API Group can have only one Idempotency Policy. If both an API and its API Group have one, the API's policy is used. The policy runs after all other inbound policies. If it rejects a request, any rate limit or quota counted for that request is rolled back.
Notes
Duplicates are checked per API and per client. The same identifier sent to a different API, or by a caller with a different access profile, is not a duplicate.
A duplicate gets 409, not the first response. Have your clients treat 409 as "already processed", not as a failure to retry.
Choose a window that covers how long your clients keep retrying. Once the window ends, the same identifier is accepted again.
With Full Payload, any change to the body makes it a new request. Use Payload Fields when only some fields identify the request.