Errors
Every status code the Agents API returns, with exact bodies.
Status codes
| Status | Meaning | What to do |
|---|---|---|
401 | Missing/invalid token — {"message":"Unauthenticated."} | Issue a new token in Developer |
402 | Out of prepaid tokens | Top up, then retry; check GET /usage |
403 | Feature not enabled — body carries "feature":"ai_chat" | Contact your administrator |
404 | Not found, or not yours (agents you cannot access and chats created by other tokens 404 identically) | Treat as not found; do not retry |
409 | Email not verified — {"code":"EMAIL_NOT_VERIFIED"} | Verify the account email |
422 | Validation failed — {"message":"…","errors":{"field":["…"]}} | Fix the listed fields |
429 | Rate limited | Back off and retry |
Chat-completions error envelope
POST /chat/completions alone uses the standard completions error shape:
{"error": {"message": "…", "type": "invalid_request_error", "code": 400}}Types: invalid_request_error (400/404), insufficient_quota (402), api_error (500/502).
Out of tokens (402)
Exact body when the prepaid balance is exhausted while sending a message:
{"error": true, "insufficient_tokens": true, "payer_is_self": true,
"message": "You are not subscribed or your token limit is reached. Please recharge to continue chatting."}When a workspace member is spending the workspace owner’s balance, payer_is_self is false and the message reads: “This workspace is out of tokens. Please ask the workspace owner to recharge.”
Generation failure (422)
If the assistant cannot produce a reply, the API returns 422 and rolls back your just-sent message so a retry re-runs cleanly:
{"error": true, "message": "The assistant could not generate a response. Please try again.",
"content": "<your original message, echoed back>"}Retry with the same content; you are not charged for failed generations.