Guides
Handling failures
What your code should do for each of the eleven ways a run can fail.
A run that ends FAILED names the reason in terminal.status and explains it in terminal.reason. Branch on
terminal.status, and use terminal.reason for logs and for people. Runs that end provider_failed or
browser_error aren't charged; see Billing.
terminal.status | What to do |
|---|---|
unverified | Don't treat the result as done. For a low-stakes task, show result.final_text as unconfirmed if it is present; otherwise retry once with a more specific prompt, or ask the user. |
not_possible | Tell the user why, using terminal.reason. Don't retry the same prompt. |
needs_user | Ask the user to complete the step on the website themselves, then retry. |
session_expired | Send the user through the auth link again. Until then, creating runs returns 409 CONNECTION_REAUTHORIZATION_REQUIRED. |
site_error | Retry later with backoff. The website was failing, blocking, or rate limiting. |
blocked_policy | Fix the prompt. It asked for another site, another account, or something the connection isn't for. |
budget_exhausted | Split the task into smaller prompts, or narrow it with start_url. |
no_progress | Rephrase the prompt with a clearer goal or a start_url, and retry once. |
timed_out | Rephrase the prompt with a clearer goal or a start_url, and retry once. |
provider_failed | Retry with backoff. Nothing about the prompt caused it. |
browser_error | Retry with backoff. If it persists on one connection, revoke and reconnect it. |
Two buckets
- Needs a person.
unverified,not_possible,needs_user,session_expired,blocked_policy. Show the user what happened and what they can do. - Try again later.
site_error,budget_exhausted,no_progress,timed_out,provider_failed,browser_error. Retry with backoff, adjusting the prompt where the table says so.
Retrying safely
A retry with a new Idempotency-Key starts a new run. If the previous run changed something on the website,
such as sending a message, placing an order, or deleting a record, a new run may repeat that action. Check
result.evidence.side_effects, when present, to see what already happened before starting another run.
Reuse the same key and body when retrying a create request whose response you didn't receive. That returns the original execution if it was created, including a failed one. Use a new key only when you intend a new run.
Next steps
Idempotency has the rules for keys. Re-authorization
walks through the session_expired path.