Errors

Every OpenLLM error uses one JSON envelope. The machine-readable code is type; match on it, not on message.

{
  "error": {
    "message": "OpenLLM: payment required — free tier exhausted",
    "type": "free_tier_exhausted"
  }
}

• Some types add fields, such as param and issues for invalid options, or tokens_used for the token limit.
• Unexpected server errors return 500 internal with a reference id in the message and, on most endpoints, in the x-openllm-error-ref response header. Include it when you contact support.
• Errors from a provider are passed through with the provider's own type. See Provider errors.

Errors that OpenLLM returns before routing (authentication, plan limits, invalid requests) never trigger fallback. Provider failures before the first output do: OpenLLM tries the next model in the chain. See Routing.

Find your error

Authentication and account

auth_error

HTTP 401, 403, or 503 · Origin: gateway, before routing

What to do

• 401: send Authorization: Bearer sk-llm-… or x-api-key: sk-llm-…. See Authentication.
• 401 with a key that used to work: check that it still exists on Devices & keys. If your vault was reset, create a new key. See This key belongs to a previous vault.
• 403 suspended: contact [email protected].
• 503: retry after the retry-after delay.

Retryable: only the 503s. Triggers fallback: no.

vault_state

HTTP 409 · Origin: gateway, on chat, messages, responses, and search

vault is uninitialized; finish onboarding before calling /v1/*

Cause: the vault for your account isn't set up yet.

What to do

• Sign in at https://www.openllm.sh and finish vault setup on Get started. See Security.

Retryable: after setup. Triggers fallback: no.

Plan limits

free_tier_exhausted

HTTP 402 · Origin: gateway, on every metered /v1 endpoint

{
  "error": {
    "message": "OpenLLM: payment required — free tier exhausted",
    "type": "free_tier_exhausted",
    "tokens_used": <tokens used this month>,
    "tokens_limit": <your monthly limit>,
    "period": "2026-10"
  }
}

Cause: your Free plan has used its monthly tokens. period is the current month in UTC (YYYY-MM); the budget resets on the 1st of the next month.

What to do

• Wait for the reset, or upgrade to Pro in Settings → Billing. See Monthly tokens.

Retryable: after the reset or an upgrade. Triggers fallback: no.

payment_required

HTTP 402 · Origin: gateway

OpenLLM: payment required — Pro plan required for this endpoint

Cause: a feature that needs Pro was called from an account without it. No /v1 endpoint requires Pro.

What to do

• Upgrade in Settings → Billing. See Plans and limits.

Retryable: after an upgrade. Triggers fallback: no.

device_limit_exceeded

HTTP 403 · Origin: returned to the daemon when it connects, not to /v1 callers

{
  "error": {
    "message": "device_limit_exceeded",
    "type": "device_limit_exceeded",
    "device_cap": <devices your plan allows at once>,
    "device_count": <devices connected now>
  }
}

Cause: your plan's limit on devices connected at once is reached. Only running daemons count.

What to do

• Run openllm stop on a device you aren't using. Unpairing a device doesn't free a slot; stopping it does.
• Or upgrade for more devices. See Device limits.

The daemon keeps running and serving local requests, and retries the connection with a growing delay until a slot frees.

Retryable: yes, the daemon retries on its own.

Routing and devices

subscription_requires_daemon

HTTP 403, or 501 · Origin: hosted gateway

This chain resolves only to subscription providers (claude_code), which are served only by an OpenLLM device — and no online device of yours can serve them. Start the daemon on a device that has the provider/model (or connect it on /providers), or add a non-subscription (API-key) model to the chain.

Cause: subscription models run only on your devices. The hosted gateway first skips subscription models and tries the API-key models left in the chain; you get this error when none remain and no online device could take the request. When a device is online but not signed in to the provider, the message says so.

The same type is returned for:

• /v1/realtime on the hosted gateway (403). Realtime voice runs only on your local daemon.
• /v1/responses/compact when no device signed in to ChatGPT is online (501).
• DELETE /v1/videos/{video_id} for a subscription video job (501). The job finishes on its device.
• Image generation and edits, speech, transcription, and video jobs that resolve to a subscription provider with no device to serve them (403).

What to do

• Start the daemon on a machine signed in to the provider: openllm start. See Devices.
• Check the provider's sign-in with openllm auth status. See Subscriptions.
• Or add an API-key model to the chain. See Routing.

Retryable: once a device is online. Triggers fallback: this error is what's left after fallback.

local_requires_daemon

HTTP 403 · Origin: hosted gateway

This chain resolves only to local model servers (local_ollama), which are served only by an OpenLLM device — and no online device of yours can serve them. …

Cause: the chain contains only local models (local_*), and no online device lists the model.

What to do

• Start the daemon on the machine that runs the model server, and keep the model server running. See Local models.
• Or add an API-key model to the chain.

Retryable: once a device lists the model. Triggers fallback: this error is what's left after fallback.

missing_credential

HTTP 403 · Origin: gateway

No credential configured for provider "anthropic"

Cause: the model's provider isn't connected on Providers.

What to do

• Connect the provider. See API keys.
• Or use a model from a provider you have connected. GET /v1/models lists them.

Retryable: after connecting. Triggers fallback: yes. In a chain, a model without a credential is skipped; you see this error only when no model could be tried.

terms_rejected

HTTP 403 · Origin: hosted gateway

A Claude Pro/Max subscription credential (sk-ant-oat01- setup token) can't run on the hosted gateway — it's served only by your local OpenLLM daemon. Connect Claude Code on the daemon (Providers → Claude Code), or use a Console API key (sk-ant-api03-) here.

Cause: a Claude subscription token was saved as an Anthropic API key, and the hosted gateway refuses to send it. The x-openllm-terms-rejected header carries model=reason.

What to do

• Connect Claude Code as a subscription on a device instead. See Subscriptions.
• Or replace it with an Anthropic Console API key (sk-ant-api03-).

Retryable: no. Triggers fallback: yes. Each refused model is skipped; you see this error only when every model was refused.

device_tunnel_failed

HTTP 502 · Origin: hosted gateway, while handing a request to a device

The device serving this request failed mid-request.

Cause: the request reached one of your devices, and the connection to it broke before a response arrived. The x-openllm-served-by-device header names the device. OpenLLM does not resend it, so it can't run twice.

What to do

• Check the device with openllm status and openllmd logs on that machine.
• Retry the request.

Retryable: yes. Triggers fallback: no.

Request validation

request_error

HTTP 400, or 502 · Origin: gateway

The default type for a request OpenLLM can't serve as sent. Common messages:

Body must be valid JSON
`model` must be a non-empty string
Unknown provider in model id: foo. Expected a catalog id or a "<provider>/<model>" pair.
Fallback chain exhausted with no upstream attempt

Cause: invalid JSON, a missing or unknown model, or a body that doesn't match the endpoint's schema (400). Fallback chain exhausted with no upstream attempt (502) means no model in the chain could be tried.

What to do

• Fix the request. The message names the field.
• Check model ids with GET /v1/models.
• For the 502, check that the chain has at least one model you can use. See Routing.

Retryable: no, not without changing the request. Triggers fallback: no for an invalid body. In a chain, a model with an unknown provider is skipped.

unsupported_param

HTTP 400 · Origin: gateway, on media and embedding endpoints

{
  "error": {
    "message": "\"style\" is not supported by this model; omit it or choose a model that accepts it.",
    "type": "unsupported_param",
    "param": "style",
    "issues": [{ "param": "style", "code": "unsupported_param", "message": "…" }]
  }
}

Cause: the chosen model doesn't support an option you sent. On image generation, param names the first one and issues lists all of them, with supported values when they are known; other endpoints send the message only. OpenLLM refuses instead of dropping or changing the option.

What to do

• Use a value from supported, remove the option, or pick a model that supports it.

Retryable: no. Triggers fallback: on image generation, yes. A model that can't take the option is skipped; you see this error when no model in the chain can. Elsewhere, no.

unsupported_content

HTTP 400 · Origin: gateway

unsupported_content: model "…" does not support image content

Cause: the request contains images and the model can't read them.

What to do

• Use a model with vision support, or add one to the chain.

Retryable: no. Triggers fallback: yes. A model without vision is skipped; you see this error when it was the last model in the chain.

image_edit_unsupported_provider

HTTP 400 · Origin: gateway, on /v1/images/edits

Image editing is only available through a subscription provider today (chatgpt, grok) — "openai" has no API-key image-edit path yet.

Cause: image edits work only through the chatgpt and grok subscription providers.

What to do

• Use a chatgpt/ or grok/ image model, with a device signed in to that provider. See Subscriptions.

Retryable: no. Triggers fallback: no.

image_edit_invalid

HTTP 400 · Origin: gateway, on /v1/images/edits

Body must be valid multipart/form-data

Cause: the body isn't valid multipart or JSON, or it has no inline data: reference image. A mask returns image_edit_mask_unsupported and more than one image returns image_edit_multi_reference_unsupported (both 400). A body over the size limit returns 413.

What to do

• Send exactly one image as image=@file, or as a JSON data: URL. See Images.

Retryable: no. Triggers fallback: no.

not_found_error

HTTP 404 · Origin: gateway

Model "foo" was not found or is not accessible to this caller.

Cause: GET /v1/models/{id} found no such model or alias for your account, or a video id doesn't exist (No such video: …).

What to do

• List what you can use with GET /v1/models. Connect the provider if it's missing.

Retryable: no. Triggers fallback: no.

video_not_ready

HTTP 409 · Origin: gateway, on /v1/videos/{video_id}/content

Video is not ready yet (status: …). Poll GET /v1/videos/{video_id} until it completes.

Cause: you asked for the file before the job finished.

What to do

• Poll GET /v1/videos/{video_id} until status is completed, then download.

Retryable: yes, after polling. Triggers fallback: no.

search_credential_missing

HTTP 404 · Origin: gateway, on /v1/search

No credential configured for search provider "brave_search"

Cause: no web search provider key is connected.

What to do

• Connect a Brave Search API key on Providers. See Web search.

Retryable: after connecting. Triggers fallback: no.

search_provider_unknown

HTTP 400 · Origin: gateway, on /v1/search

Cause: your account names a search provider OpenLLM doesn't know.

What to do

• Reconnect web search on Providers.

Retryable: no. Triggers fallback: no.

search_upstream_error

HTTP 502 · Origin: search provider

Search provider returned 429: …

Cause: the search provider returned an error. The message includes its status.

What to do

• For 429 or 5xx, retry later. For 401 or 403, check the key on Providers.

Retryable: depends on the provider's status. Triggers fallback: no.

Provider errors

When a provider fails before sending any output, OpenLLM tries the next model in the chain. When every model fails, you get one provider's error with that provider's HTTP status, message, and type (for example rate_limit_error or invalid_request_error). The x-openllm-resolved-model and x-openllm-chain headers tell you which models were tried.

Once a stream has started, a provider failure ends the stream. There is no fallback after output.

upstream_error

HTTP 502 · Origin: provider

The image provider returned a response this gateway could not read.

Cause: the provider answered with something OpenLLM couldn't use, such as an unreadable media response, no audio, or a ChatGPT response that failed partway.

What to do

• Retry. If it persists, try another model.

Retryable: yes.

network_error

HTTP 502 · Origin: gateway, reaching a chat provider

upstream transport failed

Cause: OpenLLM couldn't connect to the provider.

What to do

• Retry. Check the provider's status page if it continues.

Retryable: yes. Triggers fallback: yes, before output.

upstream_connection_error

HTTP 502 · Origin: gateway, reaching an image, audio, or video provider

Cause: OpenLLM couldn't connect to the media provider. The message carries the connection error.

What to do

• Retry.

Retryable: yes.

openai_error

HTTP the provider's status · Origin: an OpenAI-format provider

Cause: the provider returned an error without its own type. The message is the provider's.

What to do

• Read message. For 429, wait and retry, or add another model to the chain. For 401 or 403, reconnect the provider on Providers.

Retryable: 429 and 5xx. Triggers fallback: yes, before output.

anthropic_error

HTTP the provider's status · Origin: Anthropic

Cause: Anthropic returned an error without its own type. The message is Anthropic's.

What to do

• Same as openai_error.

Retryable: 429 and 5xx. Triggers fallback: yes, before output.

Server

internal

HTTP 500 · Origin: gateway

Internal server error (ref: 3f2b8c1e-…)

Cause: an unexpected failure inside OpenLLM. The details are logged under the reference id; the response doesn't include them.

What to do

• Retry once.
• If it repeats, send the reference id (from the message or the x-openllm-error-ref header) and the time of the request to [email protected]. See Still stuck.

Retryable: once. Triggers fallback: no.

Last updated on