Idempotency
Networks fail. Use the Idempotency-Key header on any unsafe method so retries don't double-create.
Pick a key
Any string up to 200 characters. Best keys are the natural id of the work being done — your invoice number, transfer id, or a UUID you mint per request.
Idempotency-Key: invoice-2026-00042What happens on replay
| Scenario | Response |
|---|---|
| Same key, same body, 2xx within 24h | Saved response, Idempotent-Replayed: true header. |
| Same key, different body | 409 idempotency_conflict. |
| Same key, original still in flight | 409 idempotency_in_progress + Retry-After: 2. |
| Same key, original failed (4xx/5xx) | Treated as fresh — the failed attempt is forgotten so retries can succeed. |
| Key expired (>24h) | Treated as fresh. |
Scope
Keys are scoped to your organization. Two different orgs can reuse the same key string without collision.
Pattern: always set an idempotency key on creates. Even a PATCH that "looks safe to retry" benefits — a botched retry that double-applies a payment is a customer-service problem.