Skip to main content
To handle everything that can go wrong with a run, branch on whether the request itself was rejected or the run later failed, rather than assuming a successful call means a usable answer. Agent fails in two different places, and they need different handling: the same split Fetch makes between a rejected request and a failed page. A rejected request raises immediately. Nothing runs, and nothing costs anything: an empty query, an unknown field, or a malformed output_schema wrapper all fail this way. A failed run does not raise: create and get return normally, and the run reaches a terminal status: "failed" with stop_reason saying why.

Over REST

A rejected request is a non-200 with the same {"error": {"code": ..., "message": ...}} envelope Search, Answer, Fetch, and Monitor use, so shared error-handling code across endpoints works for Agent, too. Branch on code; message is prose for logs and its wording can change.
The full status/code table is in Reference.

A failed run is not a rejection

Once the server accepts a run, its eventual failure arrives as data, not as an error. Branch on status, then read stop_reason for why:
internal_error covers every fault on Seltz’s side, including retrieval outages. There is no finer split, so the only response is to retry the run. This requires a new create, since a failed run cannot resume. A run that produces no JSON output at all fails with stop_reason: invalid_output rather than returning something unparsable.

Next steps