Idempotency

Every mutation requires an Idempotency-Key so you can retry safely without creating or paying for duplicate work.

Any request that can create a resource, regenerate, revert, or spend credits requires an Idempotency-Key header containing a UUID you generate. This lets you retry a request after a network failure without risking a double charge or duplicate job.

Idempotency-Key: 019f6e13-1229-7c6c-a149-f2d6a595fb0f

The rule

Use a new key for a new intent.
Reuse a key only for the exact same route and a byte-for-byte identical body.
Changing the body under an existing key returns 409 idempotency_conflict.

Reading the response status

Status	Meaning	What to do
`201`	A new async resource or operation was accepted	Follow the relative `Location` header and poll it
`200`	A terminal result was returned (including an exact replay, where supported)	Use the result as-is
`202`	The first request’s outcome isn’t known yet	Wait for `Retry-After`, then resend the exact request with the same key
`409`	Conflicts with resource state, or the key is bound to a different request	Inspect `error.code`; do not blindly retry

Replays

When you retry an exact request, the stored result is returned with the header:

Idempotency-Replayed: true

A replay has the same status, body, and durable headers as the original. It does not reserve credits or dispatch work a second time.

The Location header

Newly created quotes and newly accepted character, regeneration, generation, audio, and voice operations return a relative Location header — poll that URL for status. Character revert completes against the character itself and does not create a separate polling resource.