Errors

Every error response from /v1/agents/* shares the same JSON envelope.

Envelope

{
  "ok": false,
  "agent": "competitive-landscaping",
  "error": {
    "code": "invalid_input",
    "message": "missing required field: 'query'"
  }
}

Error codes

Code	HTTP	When
`unauthorized`	401	Missing or invalid Bearer token / session cookie.
`invalid_input`	400	Request body failed schema validation (missing field, wrong type).
`quota_exceeded`	402	Free-plan lifetime quota exhausted. Upgrade to Pro.
`forbidden`	403	Authenticated user does not own the resource.
`not_found`	404	Agent name or referenced resource (e.g. run_id) does not exist.
`agent_failed`	500	The pipeline raised an unhandled exception. Includes the exception message.
`timeout`	504	Cloud Run cut the request at the 60-minute limit before the pipeline finished.

504 timeout behaviour

Cloud Run hard-caps every HTTP request at 60 minutes. If the underlying pipeline runs longer than that, the connection is terminated and the caller sees a 504 — but the pipeline keeps running server-side and the run is still persisted to the database. The result is reachable via the dashboard (/history) under the same account.