Retries and idempotency#
Idempotency-Key is optional for ordinary REST and source submissions, but use it whenever a request may be retried. Without it, each submission creates a new operation identity. Studio generation/run routes and credit-consuming MCP tools require a caller-provided identity.
| Situation | Next action |
|---|---|
| Timeout or dropped response | Retry the unchanged request with its original key, or inspect its known operation ID. |
| Completed result | The same key replays retained output with no additional fetch or charge. |
| 409 conflict | The key was already used for another body. Restore the original body or choose a new key for new work. |
| Terminal failure | The original key preserves the failure. Correct the cause and use a new key for a deliberate new attempt. |
| 429 admission limit | Respect Retry-After and reduce concurrency. Reuse the identity, unless the error asks you to retry with a new operation: then use a new key. |
| 410 expired content | The replay does not rerun. A new collection needs a new key and its normal credit budget. |
Idempotency is scoped to a workspace and API route. It is not a permanent content cache or a guarantee that a source never changes. REST and MCP share the identity for the same route and normalized request body.