Control plane API

Error responses

The control plane's error convention and every status it returns, distinct from the inference gateway's envelope.

Shape

A non-2xx response from the control plane is a small JSON object. Most carry a human sentence under error; schema validation failures carry a structured detail:

{"error": "project not found"}

{"detail": [{"type": "missing", "loc": ["body", "payload", "id_token"], "msg": "Field required"}]}

Render error to a person as it is; treat detail as a list of field problems.

Statuses

Status	Meaning
`400`	Bad request body or query parameters (a past expiry, an unknown route id in `allowed_models`, a credit limit below what the key has already spent, a bad `status_category`), or the account has no organisation.
`401`	No session: the `i2_access_token` cookie is missing, expired or invalid. Refresh, or sign in again.
`403`	Signed in, but missing a required role. Renaming the organisation needs `owner` or `admin`; a `member` gets this.
`404`	The referenced resource does not exist or is not this organisation's. The API never distinguishes the two.
`409`	Duplicate: an email already registered, or an organisation name already taken.
`422`	The body failed schema validation; see `detail`.
`503`	A backing service is unreachable; today only the analytics endpoints can answer this, and everything else keeps working.

The inference gateway is different

Requests to /v1/chat/completions use the OpenAI-shaped envelope, {"error": {"message", "type"}}, and their own status meanings. Those are on Errors and retries.

Something unclear or wrong on this page? Tell us. Machine-readable copies: llms.txt.