AI API error codes
A failed call uses the same envelope as a successful one: read the HTTP status code, then read response for a message describing what went wrong. Messages are stable English sentences you can log and match on, but branch on the status code.
{
"code": 403,
"title": "Forbidden",
"response": "The API key is missing the required scope: reasoning:write"
}Status codes
| Code | Title | What it means |
|---|---|---|
| 200 | OK | The call succeeded. Reads, edits, revocations and creations of apps and runs use this code. |
| 201 | Created | A key was created. |
| 301 | Moved Permanently | You called http://. Repeat the call on https://. |
| 400 | Bad Request | The body was not a JSON object, a required field was absent, or a value had the wrong type. |
| 401 | Unauthorized | No usable key was presented, or the key has expired. |
| 402 | Payment Required / Quota exceeded | The plan does not cover the action, or its token allowance is used up. |
| 403 | Forbidden | The key is unknown, suspended or revoked, or short of the required scope. |
| 404 | Not Found | No such path, or no such record in your project. |
| 413 | Payload Too Large | The request body exceeded 200,000 bytes. |
| 422 | Unprocessable entity | The body parsed but a value was refused, or the method and path do not combine into an endpoint. |
| 429 | Too Many Requests | Too many requests in a short time. Wait for the number of seconds given in the Retry-After header, then retry. |
| 500 | Internal Server Error | An unexpected fault. Retry, then report it. |
| 503 | Service Unavailable | The AI service is temporarily unavailable. Retry later. |
Authentication failures
These are checked before anything else, so they can answer any path.
| Code | Message | Cause |
|---|---|---|
| 401 | No valid API key provided. | The Authorization header is missing, does not start with Bearer , or does not carry a project key. |
| 401 | The API key has expired. | The key had an expiry date and it has passed. A key with no expiry date never raises this. |
| 403 | The API key doesn't have permissions to perform the request. | The key is unknown, suspended or revoked, or its project is no longer active. |
Note — An unknown key and a revoked key give the same
403with the same message, on purpose: the API never confirms whether a key exists.
Scope failures
An endpoint checks its scope before doing any work.
| Code | Message | Cause |
|---|---|---|
| 403 | The API key is missing the required scope: <scope> | The key holds neither *, nor <resource>:*, nor the exact scope named. |
| 403 | Cannot create a key with wider scope than the calling key. | You asked for * on a new key while your own key is narrower. |
The message names the scope that was wanted, so the fix is either to use a key that holds it or to stop calling that endpoint. See AI API keys.
Request failures
| Code | Message | Cause |
|---|---|---|
| 400 | Invalid JSON. | The body is not parseable JSON, or it is a JSON value that is not an object. |
| 413 | Request body too large. | The body exceeded 200,000 bytes. |
| 422 | The parameters were valid but the request failed. | The method and path do not combine into an endpoint (for example DELETE on an app), or a value was refused without a more specific message. |
Not found
Two different 404s exist. An unknown path is refused before any endpoint is reached:
{
"code": 404,
"title": "Not Found",
"response": "The requested resource was not found."
}A path that exists but names a record your project cannot see is refused by the endpoint, with a message naming the record type: App not found., Reasoning not found. or API key not found.
Important — A run or a key that belongs to another project returns the same
404as one that never existed, so a key cannot be used to discover what other projects hold.
Plan and quota failures
The run and app endpoints check your project's plan before acting.
| Code | Title | Message |
|---|---|---|
| 402 | Quota exceeded | Your reasoning quota is exhausted. Please wait until it resets or upgrade your plan. |
| 402 | Payment Required | The current billing plan does not allow custom app creation for this project. |
| 402 | Payment Required | The current billing plan app limit has been reached for this project. |
| 402 | Payment Required | The selected model library is not available for the current billing plan. |
Call GET /v1/ai/run-usage/summary to read the remaining allowance before you launch a run, and to find when the cycle resets. See AI quota and token usage.