Idempotency
Network calls can fail after the server has already done the work — a request
times out, a connection drops, or you get a 5xx and don't know whether the
operation went through. Retrying blindly risks doing the same thing twice
(issuing two cards, posting two transfers).
Idempotency lets you safely retry a write without that risk. You attach a unique key to each logical request; if the same key arrives again, the API returns the original result instead of performing the operation a second time.
When it's required
The Idempotency-Key header is required on every write — all POST and
PATCH operations.
Read operations (GET, and the POST .../search / POST .../lookup reads) do
not use it.
The Idempotency-Key header
| Header | Idempotency-Key |
| Format | UUID v4 |
| Scope | One key per logical request |
| Example | 550e8400-e29b-41d4-a716-446655440000 |
Generate a fresh UUID v4 on the client for each distinct operation you want to perform, and send it on the request:
Code
How it works
-
First request with a given key is processed normally, and its response is stored for 24 hours.
-
A retry with the same key and the same request body within that window returns the original stored response — the operation is not run again. The replayed response carries an extra header:
Code -
After 24 hours the key expires and is forgotten; reusing it then starts a new operation.
Key scope
A key is scoped to your client and the specific endpoint. The same key value sent to a different endpoint is treated as a separate operation, so you don't have to worry about accidental collisions across endpoints.
Retries — best practice
- Reuse the same key when retrying a request that may have already been
received — e.g. after a timeout or a
5xx. That's exactly what makes the retry safe. - Generate a new key for every genuinely new request. Reusing a key for different data is rejected (see below).
Errors
| Status | Code | When it happens | What to do |
|---|---|---|---|
400 | ERR_IDEMPOTENCY_KEY_REQUIRED | The header is missing or empty on a write request. | Add an Idempotency-Key. |
400 | ERR_IDEMPOTENCY_KEY_INVALID | The value is not a valid UUID v4. | Send a UUID v4. |
409 | ERR_IDEMPOTENCY_KEY_ALREADY_USED | The same key was already used with a different request body within the 24-hour window. | Use a new key for the new request. The original request/response are preserved. |
409 | ERR_IDEMPOTENCY_IN_PROGRESS | A previous request with this same key is still being processed. | Wait briefly and retry with the same key — once the first finishes, you'll get its result. |
Summary
| Scenario | Result |
|---|---|
| New key | Operation runs; response stored for 24h |
| Same key + same body | Original response replayed (enza-idempotent-replayed: true); not re-run |
| Same key + different body | 409 ERR_IDEMPOTENCY_KEY_ALREADY_USED |
| Same key, first still running | 409 ERR_IDEMPOTENCY_IN_PROGRESS |
| Missing / invalid key | 400 ERR_IDEMPOTENCY_KEY_REQUIRED / ERR_IDEMPOTENCY_KEY_INVALID |