> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dreamlayer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency and retries

> Retry uncertain managed requests without duplicate execution or charging.

# 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.

```text theme={null}
Idempotency-Key: checkout-greenhouse-turn-1
```

### 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

* [Resume job events](/agent-api/jobs-and-events)
* [Handle error codes](/agent-api/errors)