PyAI reference / Errors
Error codes
error.code - never on the human-readable message, which can change.{
"error": {
"message": "Rate limit exceeded. Retry after 30s.",
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"param": null
}
}Quick scan
| code | HTTP | Meaning |
|---|---|---|
unauthorized | 401 | Missing or invalid API key. |
forbidden | 403 | The key is valid but lacks the required scope. |
origin_not_allowed | 403 | A publishable token was used from an origin that isn't allow-listed. |
invalid_agent_id | 400 | session_label on an Omni URL is malformed (control characters or too long for a header value). |
credit_exhausted | 402 | The org is out of prepaid credit. |
key_budget_exceeded | 402 | The per-key monthly budget has been hit. |
insufficient_quota | 402 | The plan quota is exhausted. |
rate_limit_exceeded | 429 | The per-key or per-IP rate limit was exceeded. |
concurrency_limit_exceeded | 429 | Too many concurrent realtime sessions. |
daily_cap_exceeded | 429 | A sandbox or publishable-token daily cap was reached. |
Every code
Missing or invalid API key.
What to do: Stop and surface to the user - the key is missing or wrong.
The key is valid but lacks the required scope.
What to do: Add the scope to the key in the console; don't retry.
A publishable token was used from an origin that isn't allow-listed.
What to do: Add the origin to the allow-list; don't retry.
session_label on an Omni URL is malformed (control characters or too long for a header value).
What to do: Fix the label; don't retry.
The org is out of prepaid credit.
What to do: Add credit (or use a pyai_test_ key); don't retry.
The per-key monthly budget has been hit.
What to do: Raise the key budget; don't retry.
The plan quota is exhausted.
What to do: Upgrade the plan.
The per-key or per-IP rate limit was exceeded.
What to do: Back off and honor the Retry-After header.
Too many concurrent realtime sessions.
What to do: Wait and retry.
A sandbox or publishable-token daily cap was reached.
What to do: Wait until the cap resets.
Console and management routes (under the dashboard origin) instead use RFC 7807 application/problem+json with a request_id - a different shape from the inference envelope above.
QUESTIONS, ANSWERED
A few useful answers.
How should I use the error-code table?
Use the documented stable code to select the appropriate handling path. The table explains what each code means and which action the application or operator should take.
Should I retry every failed request?
No. Follow the guidance for the specific error. Correct request, permission or account problems before retrying, and use the documented retry guidance for transient conditions.
Where is the complete API contract?
The canonical documentation and live OpenAPI specification describe endpoints, authentication and response contracts. This page provides searchable error-code details for integration work.
Handle errors once, ship with confidence.
Start free with $50 in free credits - stable codes mean your retry logic won't drift.