Identify the failing layer first
Capture the request ID when available, session ID, turn ID, event type, time, and sanitized error. Distinguish an HTTP/API rejection, a browser stream failure, a required action, a tool error, and an environment problem. Never include keys, signing secrets, or unrestricted customer payloads in a public bug report.
Use the symptom table
These checks identify likely causes; the actual API error and current resource state take precedence. Avoid retrying a rejected request indefinitely.
| Symptom | Check | Next action |
|---|---|---|
| 401 or permission denial | Key, project, permission scope, model/API access | Correct access; never put the key in the browser |
| 429 | Rate limit versus exhausted quota in the error | Back off for rate limits; resolve quota before retrying |
| Waiting for a function | Current required_actions, tool name, turn_id and call_id | Validate and return the matching tool result |
| Waiting for compute | environment_connection action and executor health | Connect the owning environment; recheck session state |
| Idle but no answer | Root turn outcome and saved items | Do not treat idle as success |
| No streamed text | output_text.done and saved message items | Support final-only text and paginated history |
| Duplicate business action | Operation key and prior downstream outcome | Reconcile before any repeat execution |
| Deleted session, compute still billed | Provider machine state | Stop self-hosted compute separately |
Separate webhook and stream names
A webhook uses agent.session.action_required; the live stream uses agent.session.requires_action. In both cases retrieve current required_actions. Verify webhook signatures against the original body. If your database or queue cannot accept the event durably, do not return a successful acknowledgment.
Recover output without claiming event replay
Reconnect and retrieve saved items and turns; use pagination. Merge by item identity and use complete output text to replace partial buffers. Saved history does not recreate every missed intermediate event. Only finish the root workflow on its own terminal outcome, and inspect tool results even when the turn completed.
Know when to stop retrying
Stop automatic retries when credentials are invalid, arguments require correction, a side effect has an unknown outcome, or the task budget is exhausted. Preserve the session ID and show an actionable failure state. A lost connection can leave work running; a browser retry button should not silently create a second job.
Read the official reference
Check the source for current API fields, account requirements, and service limits.
OpenAI: events Sandbox recovery and cleanup API error codes