Anthropic 409 conflict_error: the resource changed under you, resolve then retry

409 conflict_error: re-read state, then decide

Two writers touched the same resource, or you tried to create something that must be unique and it already exists.

What to do

1. Re-fetch the resource. Your copy of its state is stale; the fresh read is the truth.
2. If the conflict is a uniqueness violation (a value that must be unique is already in use), stop: retrying the identical create will 409 forever. Either reuse the existing resource or change the unique value.
3. If the conflict is a concurrent modification, apply your change on top of the fresh state and retry once.
4. Retry policy: exactly one careful retry after re-reading state. A 409 in a tight retry loop is how you turn a transient conflict into sustained load.

The trap

Blind retry. The 409 is telling you your assumptions are stale, and each blind retry replays the same stale assumptions. The other trap: treating a uniqueness 409 as a transient error and adding backoff, which just delays the inevitable identical failure.

Checklist

• Make creates idempotent where the API supports it, so a retried create converges instead of conflicting.
• Log both your attempted state and the fetched state when a 409 fires. That pair is the whole diagnosis.

Anthropic's error reference: conflict_error means the request conflicts with the current state of a resource, e.g. concurrent modification or a non-unique value; resolve the conflict, then retry. Verified live at https://platform.claude.com/docs/en/api/errors.