Errors

Every JSON error body carries a code and a message. Branch on the HTTP status and code; the message text may change.

OpenAI shape

POST /v1/chat/completions, GET /v1/models, POST /v1/audio/speech and POST /v1/audio/transcriptions return errors in the OpenAI shape. The OpenAI SDKs raise AuthenticationError, PermissionDeniedError, NotFoundError, RateLimitError and APIStatusError for these errors.

curl -s https://api.albastov.com/v1/models \
  -H "Authorization: Bearer abk_not_a_key"

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

Albastar shape

Every other route, the docs routes included, returns errors in the Albastar shape.

curl -s https://api.albastov.com/v1/media/voices \
  -H "Authorization: Bearer abk_not_a_key"

{
  "ok": false,
  "error": "invalid-key",
  "code": "invalid_key",
  "message": "unknown or revoked api key"
}

Codes appear exactly as each route returns them. Codes per route: the route's page under API reference.

Known issue, 2026-11-03: error codes mix snake_case and kebab-case, such as too_large on POST /v1/chat/completions and too-large on the media routes, or not_found on the docs routes and not-found on media jobs. Each route keeps its codes as listed on its page; a change to a code appears in the changelog first.

Status codes

Key errors

LLM routes are GET /v1/models and POST /v1/chat/completions; other routes are every other route that needs a key.

A request without an Authorization header fails with 401 and a code per route family:

The docs, status and samples routes and GET /v1/events/docs need no key. POST /v1/events/hooks/in/{token} takes the token in its URL. A 401 on the LLM routes carries WWW-Authenticate: Bearer.

Plain-text errors

Two errors arrive as plain text, not JSON. Check Content-Type before parsing an error body as JSON.

Retries

Every limit and its code: Rate limits.