- Documentation
- API · Version 1.0
- Idempotency
Idempotency
On this page
The central risk of a publishing API is publishing twice. An HTTP client that loses the response to a POST will retry, and without a safeguard the second attempt would create a second publication. The API therefore requires an idempotency key on writes that create something.
Where the key is required
The Idempotency-Key header is required on:
POST /publications;POST /media.
Without it, the request is refused before anything runs:
{
"error": {
"code": "idempotency_key_required",
"message": "L'en-tête Idempotency-Key est obligatoire sur cette écriture : sans lui, une requête rejouée après un délai réseau publierait une seconde fois."
}
}
A key longer than 255 characters receives 400 idempotency_key_too_long.
Choosing a key
Derive the key from what triggers the write, rather than drawing it at random: article-42-publie-v1 is recomputed identically after your process restarts, whereas a UUID generated on the fly cannot be recovered.
If your natural key is long — a URL, a path — hash it: 'pub-'.hash('sha256', $url) fits in 68 characters and stays deterministic.
A key is never shared between two API clients: the same value used by two clients designates two distinct requests.
What happens on receipt
| Situation | Response |
|---|---|
| Unknown key | The request runs. If it succeeds, its response is stored. |
| Known key, same body, response stored | The stored response is returned as is, with the Idempotent-Replay: true header. Nothing is created again. |
| Known key, same body, request still in progress | 409 idempotency_key_in_flight. |
| Known key, different body | 409 idempotency_key_reused. |
Returning the original resource for a different body would make the client believe its new request had been taken into account: that is why this case is a conflict.
Mechanism details
- Only successes are stored. An error response (status 400 or above) releases the key: the request can be corrected and then replayed with the same key.
- The key is reserved before execution. Two concurrent requests carrying the same key cannot both run; the second receives
409 idempotency_key_in_flight. - An abandoned reservation is taken over. If the process that held the key stopped without responding, the reservation is considered lost after five minutes, and the next request carrying this key runs normally.
- A key lives 24 hours. After that, it is forgotten: the same value becomes an unknown key again. Do not rely on a key older than one day to prevent a duplicate.
- The body fingerprint ignores the order of an object's keys, at every level:
{"a":1,"b":2}and{"b":2,"a":1}are the same body. Lists, however, keep their order:destination_idsin a different order is a different body. - For a file upload, the fingerprint covers the content (SHA-256 digest), not the name: sending the same image again under another name is the same upload.
Other writes
Transitions — publish, cancel, retry — are called without a key. They are idempotent by nature: each one refuses the state it produces, and a second call responds 409 transition_not_allowed without changing anything.
Webhook writes do not require one either: registering the same endpoint twice is visible and can be fixed, whereas publishing twice cannot.
Retrying without publishing twice
The rule fits on one line: keep the key, replay the request.
| Situation | Key | Body |
|---|---|---|
| Network cut, no response | the same | unchanged |
5xx |
the same | unchanged |
429 |
the same | unchanged |
409 idempotency_key_in_flight |
the same, after a short delay | unchanged |
422 |
the same | corrected |
400 on the key |
corrected | unchanged |
| Intentionally different content | new | new |
A replay that returns the stored response carries Idempotent-Replay: true: nothing was created this time, which keeps you from counting the same publication twice in your own statistics.