Skip to main content

​
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

StatusWhenDetailRetry?
401No key in the Authorization or X-API-Key headerMissing API keyNo — fix auth
401Unknown or disabled keyInvalid API keyNo — check the key’s state in the app
403Body template_id ≠ the key’s agentAPI key is not valid for the requested templateNo
404The key’s agent was deleted, or the run ID is unknown, in another org, or another agent’sAgent template not found · Agent not foundNo
409The agent is archived(archived-template message)No — unarchive it in the app
413Decoded files total over 10 MiBtotal file size exceeds the allowed limitNo — shrink the payload
422A file is not valid base64file '<name>' is not valid base64No
422The organization has no usable inference model(allowlist message)No — fix the organization’s model configuration in the app
422Schema validation (name length, >10 files, missing fields, bad UUID)FastAPI validation arrayNo
502Event-history lookup failed (GET only)event history lookup failedYes — with backoff
503Event history temporarily unavailable (GET only)event history is temporarily unavailableYes — 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.