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.

application/json

{
  "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 403 with 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:

application/json

{
  "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 404 as 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.

Send Comments

Contact support