Errors

Last verified: 2026-06-20 (Task #390 — User APIs documentation).

The Agent Runs API returns resource objects on success and a simple error object on failure:

{ "error": "Forbidden" }

For request-body validation failures, error is an array of structured validation issues:

{ "error": [ { "path": ["tripId"], "message": "Required" } ] }

Status codes

Status	Meaning	Typical `error`
`400`	Malformed body, or a control `action` invalid for the run's current state.	`"Cannot start a run that is already running"` or a validation-issues array
`401`	No valid session cookie or bearer token.	`"Authentication required"`
`403`	The run (or, on create, the target trip) belongs to another user.	`"Forbidden"`
`404`	The run, trip, or artifact was not found.	`"Run not found"`
`500`	Unexpected server error.	`"Internal server error"`

The SSE stream endpoint authenticates with the session cookie only; a bearer token there yields 401. Use the events polling endpoint when you only have a bearer token. See streaming.md.
Within the stream, transport-level problems arrive as an error frame ({ "type": "error", … }) rather than an HTTP status, because the 200 response has already begun.

Last verified: 2026-06-20 (Task #390 — User APIs documentation).

The Agent Runs API returns resource objects on success and a simple error object on failure:

{ "error": "Forbidden" }

For request-body validation failures, error is an array of structured validation issues:

{ "error": [ { "path": ["tripId"], "message": "Required" } ] }

Status	Meaning	Typical `error`
`400`	Malformed body, or a control `action` invalid for the run's current state.	`"Cannot start a run that is already running"` or a validation-issues array
`401`	No valid session cookie or bearer token.	`"Authentication required"`
`403`	The run (or, on create, the target trip) belongs to another user.	`"Forbidden"`
`404`	The run, trip, or artifact was not found.	`"Run not found"`
`500`	Unexpected server error.	`"Internal server error"`

The SSE stream endpoint authenticates with the session cookie only; a bearer token there yields 401. Use the events polling endpoint when you only have a bearer token. See streaming.md.
Within the stream, transport-level problems arrive as an error frame ({ "type": "error", … }) rather than an HTTP status, because the 200 response has already begun.