Errors and what to do

401 and 400: your key and the model field

Status	Message	What to do
`401`	This credential is not an active xpander key.	The key is wrong, revoked or missing. Check what your coding tool sends, or create one in AI models & keys.
`401`	This xpander key has expired.	Create a new key in AI models & keys.
`400`	Name the model to call in the request’s model field.	Set `model`.

403: the model

Status	Message	What to do
`403`	This model is not enabled for you on the xpander AI Gateway.	Pick a model from AI models & keys, or ask an admin to enable it in Models. A model on your own endpoint is called `<provider ID>::<model>`, as `/v1/models` lists.
`403`	Model calls for this model or this account are paused by your xpander admin.	Pick another model, or ask your admin.
`403`	Your organization’s AI Gateway settings do not allow this kind of provider access for you.	Your license model doesn’t allow how this call would be paid. Ask your admin.

403: provider keys and endpoints (admin fixes)

An admin fixes all of these in Models (Providers and keys).

Status	Message	What it means
`403`	No provider key is set up for this model in your xpander organization.	Add a key for the provider. On Hybrid or Air-Gapped, every provider in use needs your own key, in Models or on the install (`secrets.static`).
`403`	Your organization has no … key on the xpander AI Gateway for this model.	Add a key for the provider.
`403`	Your organization has no … key stored in xpander for this model. Tools on your computer use the keys stored in xpander, not your own environment’s credentials.	Hybrid: people’s coding tools go through xpander cloud, which can’t use credentials inside your install. Store a key in Models.
`403`	The model provider refused the key your organization set up for this model.	The key is revoked, expired or lacks access. Replace it.
`403`	Your organization’s … key is stored without its endpoint.	Add the Azure endpoint. Other models work meanwhile.
`403`	The endpoint configured for this model’s provider key is not a reachable provider address.	Set a public `https` endpoint (Model endpoints). On xpander cloud, saving a private one fails with Model endpoints are called at public addresses here, so this endpoint was not saved.

429, 402 and 403: budgets, credits, rate limits and paused accounts

Status	Message	What to do
`429`	The daily / weekly / monthly spending limit set for this … on the xpander AI Gateway is reached until … UTC. Ask your admin to raise it, or wait.	A budget set to Block is spent. Wait, or ask an admin to raise it.
`402`	Your xpander organization reached its spending limit, so model calls are paused.	An admin raises it in Budgets.
`402`	Your xpander organization is out of credits, so model calls are paused.	An admin adds credits in billing.
`403`	Your xpander account is paused, so model calls are not available.	Contact your xpander admin.
`403`	Your xpander organization is not active, so model calls are paused.	An admin reactivates the organization.
`429`	The request rate set for this … is reached.	Retry in a minute. Coding tools and SDKs retry on their own.
`429`	Too many calls are running at once for this …	Retry when one finishes. Coding tools and SDKs retry on their own.

403 and 429: your own Claude plan

Status	Message	What to do
`403`	Your own Claude plan is not enabled for this call on the xpander AI Gateway …	Your organization doesn’t allow it for you, the call isn’t from Claude Code, or the model isn’t Anthropic’s Claude. Sign out of the plan in Claude Code, or ask your admin.
`429`	Your Claude plan’s usage limit is reached until …, and plan calls are set to wait for the plan rather than use company models.	Wait, or choose Continue on company models in AI models & keys if allowed.
`403`	Your Claude login expired.	Run `/login` in Claude Code.
`403`	Anthropic did not allow this call on your Claude plan.	Pick another model.

503, 404 and 403: the gateway itself

Status	Message	What to do
`503`	The AI Gateway could not load your organization’s settings just now.	Retry in a few seconds.
`503`	The AI Gateway could not verify this key just now.	Retry in a few seconds.
`503`	The AI Gateway could not load the provider key for this model just now.	Retry in a few seconds.
`404`	The AI Gateway serves model calls only (messages, chat completions, responses, embeddings, token counting).	Call `/v1/messages` (and `/v1/messages/count_tokens`), `/v1/chat/completions`, `/v1/responses` or `/v1/embeddings`. `/v1/models` lists your models.
`403`	This call was routed to a model outside your organization’s settings, so it was not sent.	Retry.

When the gateway is unavailable

Agents call models only through the gateway, so after 30 seconds without it:

xpander Chat shows AI Gateway is unavailable. Agents can’t run right now. We’ll reconnect automatically.
New runs are refused, and running ones stop at their next model call, with This run stopped because the AI Gateway is unavailable.
Coding tools and SDKs get 503 with a Retry-After header.

Nothing is sent to a provider any other way. The gateway usually reconnects within a minute. On a self-hosted install, new runs are refused with The xpander AI Gateway is unavailable right now until its pods are healthy: kubectl -n <namespace> get pods -l app=llm-gw should show two llm-gw pods (one on a single-node install.sh cluster), each 1/1 and Running (Self-hosted).

Find a refused call in Logs

Read its Gateway decisions.

Add a provider key

Fix a missing or refused key.

Govern

Company Brain

AI Gateway

Deploy

Integrations

Licensing and identity

Security and compliance

Errors and what to do

Find your error

When the provider refuses

Next steps

Find a refused call in Logs

Add a provider key

​Find your error

​When the provider refuses

​Next steps

Find a refused call in Logs

Add a provider key

Find your error

When the provider refuses

Next steps