Idempotency
Mutating public API docs must be precise about retry safety. Today, universal Idempotency-Key behavior is a target standard, not a published contract.
Retry posture
For POST, PUT, PATCH, and DELETE endpoints, retry only after checking endpoint-specific state unless that endpoint explicitly documents idempotent behavior.
Current rules
| Topic | Current | Rule |
|---|---|---|
| Universal header | Idempotency-Key is not declared as a universal OpenAPI header. | Do not document universal header support yet. |
| Body keys | Some schemas may expose body-level idempotencyKey fields. | Treat those as endpoint-specific compatibility fields. |
| Safe retries | Not guaranteed for mutating endpoints. | Check latest resource, status, job, or batch state before retrying. |
| Conflict behavior | Same-key changed-payload behavior is not globally defined. | Do not promise 409 replay semantics until E3 lands. |
Retry posture
| Situation | Current guidance |
|---|---|
| Network timeout before any response | Fetch or poll endpoint-specific state first. If no state can be checked, retry only when duplicate local records or external effects are acceptable for that endpoint. |
| HTTP 202 accepted | Store the returned job, batch, or resource ID and poll the documented status endpoint instead of resubmitting immediately. |
| HTTP 409 conflict | Fetch latest state and reconcile. Do not assume same-key replay, changed-payload detection, or in-flight locking unless documented. |
| HTTP 429 rate limit | Back off conservatively. Do not use idempotency keys as a substitute for rate-limit handling. |
| 5xx server failure | Retry only after checking whether the resource, job, batch, file, payment, communication, or external transaction already exists. |
Target standard not yet published
| Target | Publication status |
|---|---|
| Idempotency-Key header | Target standard only. Not declared as a universal OpenAPI parameter. |
| Scoped request fingerprint | Target standard only. Key scope, request body hash, tenant scope, and expiration are not public contract yet. |
| Replay response | Target standard only. Same-key same-payload replay behavior is not global. |
| Changed-payload conflict | Target standard only. Same-key different-payload response shape is not global. |
| In-flight duplicate handling | Target standard only. Pending, locked, or retry-after semantics are endpoint-specific. |