Error codes
Inference and data-plane errors use the OpenAI shape. Branch on the stable 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 | agent_id on a realtime/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.
agent_id on a realtime/Omni URL is malformed (control characters or too long for a header value).
What to do: Fix the id; 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.
Handle errors once, ship with confidence.
Start free with $50 in free credits - stable codes mean your retry logic won't drift.
No credit card - OpenAI-compatible - cancel anytime