Errors | Council developer console

Errors use standard HTTP status codes and a JSON body with a stable code and a readable message. When a chat, search, or billing request body fails validation, the error adds a details list that points at the fields to fix.

Error body

{
  "error": {
    "code": "insufficient_scope",
    "message": "API key is missing required scope: kb:search"
  }
}

Error codes

Status	Code	Meaning	What to do
`400`	`invalid_request`	The request is malformed or breaks a limit.	Read the message and any details, fix the request, and send it again.
`401`	`missing_api_key`	No bearer token was sent.	Add the Authorization header.
`402`	`payment_required`	The balance is empty or cannot cover max_tokens.	Add funds, or lower max_tokens.
`403`	`insufficient_scope`	The key lacks a scope or knowledge scope the request needs.	Create a key with that scope.
`403`	`invalid_api_key`	The key is malformed, unknown, revoked, or expired.	Check the key or create a new one.
`413`	`request_too_large`	The upload is larger than the limit.	Split the document or compress it.
`429`	`rate_limited`	The key reached its per minute limit or monthly token cap.	Wait and retry with exponential backoff.
`500`	`server_error`	Something failed on our side.	Retry with backoff.
`502`	`billing_provider_error`	A checkout session could not be created.	Retry in a moment.
`502`	`model_error`	The model service returned an error or could not be reached.	Retry with backoff.
`503`	`billing_not_configured`	Purchases are not available in this environment.	Use the environment where billing is set up.
`503`	`retrieval_unavailable`	Retrieval could not run.	Retry, or set citations.required to false to answer without sources.
`504`	`model_timeout`	The model took too long to answer.	Retry, or lower max_tokens.

Retrying

Retry 429, 500, 502, 503, and 504 with exponential backoff and a little jitter. Do not retry 400, 401, 402, or 403 without changing the request, the key, or the balance.