Every POST, PUT, PATCH, or DELETE can carry an Idempotency-Key header. Coffrify stores the request hash and response for 24 hours. Repeating the same key and same request body returns the original response with X-Coffrify-Idempotent-Replay: true and never re-executes the handler.
Headers
| Header | Direction | Value |
|---|---|---|
| Idempotency-Key | Request | Your UUID. 16-255 chars, case-sensitive. |
| X-Coffrify-Idempotent-Replay | Response | true when the body was served from the replay cache. |
Error codes
| Code | HTTP | Trigger |
|---|---|---|
| idempotency_conflict | 409 | Same key + DIFFERENT body. We refuse to swap the response. |
| idempotencyinprogress | 409 | Concurrent retry, the original handler is still executing. |
SDK behaviour
The official SDKs auto-inject a UUID v4 on every write call. You almost never need to set it by hand. Override only if you are orchestrating an external retry loop and need the key to be deterministic.
Retention
Cached responses live for 24 hours from first observation. Keys are GC after that — a key reused outside the window is treated as fresh.