Idempotent writes

A client that retries a write after a timeout can't tell whether the first try worked. So every route but a GET honours the Idempotency-Key header: the client sends the same key with each try, and a repeat gets the first try's answer. The runtime handles the key entirely; the action never sees it.

HTTP already calls PUT and DELETE idempotent, but a retried DELETE answers 404 where the first answered 204, and the action behind any write may raise events or call providers. So the key covers them too.

• Before the action runs, the runtime claims the key, scoped to the caller.
• Afterwards, it keeps the response with a digest (a hash) of the request, in the action's transaction, for 24 hours.
• A repeat gets the kept response.
• The same key with a different request fails idempotency_key_reused (422). A repeat while the first is still running fails conflict (409).
• Successes and failures the action returns are kept. unavailable and internal failures are not, so a retry runs again.
• Calls to outside services in the action send keys derived from the client's key (Calling).

An API can require the key with idempotency: Idempotency.required, and OpenAPI lists the header. When a repeat counts as the same request is under How failures reach the client. The rest is in the design notes, "Idempotency keys".