Errors and retries

Error body

Failures return {"detail": "<reason>"}. Request validation is the exception: a schema violation returns 422 with a body that lists each issue in FastAPI’s format:

422 validation shape

{
  "detail": [
    {
      "type": "string_too_long",
      "loc": ["body", "name"],
      "msg": "String should have at most 200 characters"
    }
  ]
}

Status codes

Status	When	Detail	Retry?
`401`	No key in the Authorization or X-API-Key header	`Missing API key`	No — fix auth
`401`	Unknown or disabled key	`Invalid API key`	No — check the key’s state in the app
`403`	Body template_id ≠ the key’s agent	`API key is not valid for the requested template`	No
`404`	The key’s agent was deleted, or the run ID is unknown, in another org, or another agent’s	`Agent template not found` · `Agent not found`	No
`409`	The agent is archived	`(archived-template message)`	No — unarchive it in the app
`413`	Decoded files total over 10 MiB	`total file size exceeds the allowed limit`	No — shrink the payload
`422`	A file is not valid base64	`file '<name>' is not valid base64`	No
`422`	The organization has no usable inference model	`(allowlist message)`	No — fix the organization’s model configuration in the app
`422`	Schema validation (name length, >10 files, missing fields, bad UUID)	`FastAPI validation array`	No
`502`	Event-history lookup failed (GET only)	`event history lookup failed`	Yes — with backoff
`503`	Event history temporarily unavailable (GET only)	`event history is temporarily unavailable`	Yes — with backoff

Retry guidance

Because GET /v1/agents/{agent_id} is read-only, you can retry it freely. If it returns 502 or 503, back off exponentially (1s, 2s, 4s, up to about 30s) and keep polling. A 404 usually means you’re using the wrong key for the agent you’re querying. IDs from other organizations or agents also return 404, the same response as a nonexistent ID.

Don’t automatically retry POST /v1/agents. This endpoint doesn’t support idempotency keys, so retrying a create request starts a second run. Only retry a create if you received no HTTP response at all, and reconcile what actually ran afterwards.

Overview

Agents

Schema

Error body

Status codes

Retry guidance

​Error body

​Status codes

​Retry guidance

Error body

Status codes

Retry guidance