One key per logical request
Set Idempotency-Key to an opaque identifier with 1–100 letters, digits, underscores, or hyphens. Do not put names, record IDs, or other PHI in it. Idempotency is scoped to the Gateway API key. A different API key is a different idempotency scope.
Idempotency-Key: summary_job_8f7b2dDuplicates are blocked, not replayed
After a request record is created, a second request with the same key receives 409. An equivalent validated request yields request_already_submitted; a changed request yields idempotency_conflict. The safe message includes the prior request ID and state. The original response is not returned because its content is not stored.
There is no automatic expiry window implemented for these records. Do not recycle an idempotency key for a new job.
Retry decisions
| Situation | Recommended handling |
|---|---|
| Validation/auth/policy rejection before dispatch | Correct the cause. Reuse the logical idempotency key only while no request was recorded. |
| 429 before dispatch | Back off with jitter and bounded retries. The gateway does not currently send Retry-After. |
| 409 | Look up the original request in Activity. Do not replace the key just to force another generation. |
| 502 provider_rejected | The recorded request failed and its hold was released. A new attempt is a new logical request and needs a new key. |
| Timeout, connection loss, or provider_outcome_unknown | The provider may have run. Do not blindly retry with a new key. Check metadata and reconcile first. |
A client timeout does not cancel provider work
The provider timeout is 60 seconds. The streaming transport has a 65-second lifetime including downstream backpressure. A disconnect or Stop action requests upstream cancellation. If reliable final usage is unavailable, the request becomes reconciliation_required and its reservation remains held. If final usage was already known, the actual charge remains settled even if the last event did not reach the client. Do not automatically resubmit with a new request ID.
Uncertain outcomes hold credits
Pending requests on restart become reconciliation_required. Their maximum reservation remains held until an operator can compare the provider record and settle or release it. This exception workflow is currently an operational limitation of the preview.