Errors

Updated 2026-10-29.

Every error response has a JSON body with a code and a message.

Example

curl -s https://citadel.albastov.com/v1/models -H "Authorization: Bearer hlk_not_a_key"

401

{"error": {"code": "invalid_api_key", "message": "The API key is unknown or revoked", "type": "invalid_request_error"}}

OpenAI format

LLM routes return errors in the OpenAI format. The OpenAI SDKs raise AuthenticationError, NotFoundError, RateLimitError and APIStatusError for these errors.

503

{
  "error": {
    "message": "Loading qwen3.8-27b; retry in 150 s",
    "type": "model_loading",
    "code": "model_loading",
    "model": "qwen3.8-27b",
    "state": "starting",
    "retry_after_s": 150
  }
}

Field	Value
`code`	Error code, `snake_case` (except `gpu-busy`, `llm-unavailable`)
`type`	OpenAI error type, or the `code` for model errors
`message`	Human-readable text
Other fields	Per code

Branch on the HTTP status and code. The message text can change.

LLM error codes and fields: Chat completions errors.

Citadel format

All other routes, including the docs routes, return errors in the Citadel format.

404

{"ok": false, "error": "not-found", "code": "not_found", "message": "not found"}

Field	Value
`ok`	`false`
`code`	Error code, `snake_case`
`message`	Human-readable text
`error`	`code` in `kebab-case` (legacy; use `code`)
`detail`, `meta`	Optional context

Status	Code
400	`bad_request`
401	`unauthorized`
403	`forbidden`
404	`not_found`
429	`rate_limited`
500	`internal`
501	`not_implemented`

Retries

Status	Retry
400, 401, 403, 404, 413, 415	No
429 `daily_limit`, `daily_tokens`	After 00:00 UTC
429, other codes	After `Retry-After`
500	Once; then report the `X-Request-Id`
502	After 5 to 10 s
503	After `Retry-After`
524	No; stream the request

Cloudflare errors

Cloudflare returns the following errors as plain text, before the request reaches Citadel. Check Content-Type before parsing an error body as JSON.

Status	Body	Cause
403	`error code: 1010`	Blocked client signature, e.g. Python `urllib`
502	`error code: 502`	Citadel unreachable
524	`error code: 524`	No response headers within about 100 s