Skip to main content
HTTP status: 409

​
Error message

Example: conversation version mismatch: expected 2, current 5.

​
When this error occurs

POST /agents/conversations/{id}/runs was called with an expected_version that no longer matches the conversation’s current head. This is an optimistic-concurrency guard: the API rejects the run before starting a workflow that would conflict at finalize time. It happens when another writer (a previous run, or a concurrent caller) advanced the conversation between the time you read version and the time you posted the new run.

​
How to fix

  1. Re-read the conversation via GET /agents/conversations/{id} to get the current version.
  2. If you were resuming from a requires_action run, also re-read the latest assistant turn via GET /agents/conversations/{id}/messages?since={your_known_version} to learn whether the pending tool calls have changed.
  3. Retry the run with the fresh version.

​
Race-free continuation pattern

For tool-output resumes, always refetch the conversation’s version immediately before posting — don’t rely on a value cached from earlier in the conversation’s lifecycle.

​
Idempotent retries

The version check runs before the client_op_id idempotency lookup. Re-posting a client_op_id returns the original run only while expected_version still matches. After that run’s messages land, the conversation’s version has moved on, so the same retry gets this 409. Read the original run with GET /agents/runs/{id} instead of re-posting.