Idempotency

Keel documents idempotency separately for the canonical permit flow and the execution routes.

At a glance

Route family	Where idempotency goes
`POST /v1/permits`	JSON body `idempotency_key`
`POST /v1/permits/{permit_id}/usage`	JSON body `usage_idempotency_key`
`POST /v1/executions`	`Idempotency-Key` header
`POST /v1/execute`	`Idempotency-Key` header
`POST /v1/proxy/*`	`Idempotency-Key` header

Route:

Canonical field:

Behavior:

scope is per project
same key plus the same semantic payload replays the prior permit response
same key plus a different semantic payload returns 409 conflict
if the client omits idempotency_key, Keel generates a server-side idempotency key for that permit
replay is still route-dependent: stale allow permits with inactive reservations can expire or revalidate instead of replaying the original allow body

Route:

Canonical field:

Behavior:

use the same key when retrying the same permit closeout
same key plus the same closeout values replays the existing closeout response
same key plus different closeout values returns 409 conflict
this is a narrower permit-first closeout contract, not proxy-strength execution replay binding

Routes:

Canonical field:

Behavior:

reuse the same header value when retrying the same execution request
if the header is omitted, the request still runs, but retries are treated as new executions
proxy routes document the strongest replay contract: same key plus the same payload replays the cached response, and same key plus a different payload returns 409 conflict
execution routes use the same header-based retry pattern, but you should still treat the header as part of the public route contract rather than assume identical semantics across every route family
/v1/executions and /v1/execute do not currently document the same proxy-strength request-hash replay binding as the proxy routes

Permit creation uses a body field. Execution routes use a header. Use the documented field for each route family.