Skip to main content

​
Idempotency and retries

​
What this lets you do

Recover from timeouts and disconnects without creating duplicate execution or charging.

​
What you need

  • A caller-owned stable identifier for each logical mutation
  • Persisted execution IDs and event IDs
  • Access to canonical execution state

​
Steps

​
1. Assign one key

Assign one caller-owned Idempotency-Key to each logical mutation. Reuse it only for a byte-equivalent request after an uncertain response.

​
2. Read state before retrying

Do not generate a new key automatically after a timeout or disconnect. First read canonical execution state or reconnect to the event stream.

​
3. Apply the retry decision

  • 401: fix authentication. Do not retry unchanged.
  • 402: add credits or use a test key.
  • 409: inspect the conflict. The idempotency key may have different request bytes.
  • 429: respect the response and back off.
  • 5xx or lost response: query canonical state and reuse the same key for the same logical request.
Idempotent replay must not create a second provider call or charge.

​
Confirm it worked

Repeating byte-equivalent request data with the same key returns the same logical execution. A different body with that key receives a conflict.

​
Common errors

  • Reusing one key for different JSON creates an idempotency conflict.
  • Creating a new key after a timeout can create new work.
  • Retrying 401 unchanged cannot repair authentication.

​
Troubleshooting

Compare the request body bytes, key, execution ID, and canonical status. Do not include prompts, keys, or image data in logs.

​
Next steps