Error 503 model_disabled: What It Means and How to Handle It

Error 503 model_disabled means the model you requested is currently switched off on Zukko. Other models keep working, and your key and balance are fine. Below is how to recognize this error, where to get the list of enabled models, how to switch in Claude Code and Cursor, and how to write code that falls back to another model on its own.

What model_disabled means

The server response looks like this:

{
  "error": {
    "message": "Модель 'claude-opus-5-5' временно недоступна. Актуальный список: GET /v1/models",
    "type": "service_unavailable",
    "code": "model_disabled",
    "param": "model"
  }
}

• HTTP status: 503.
• code: model_disabled; check this in your code.
• message: text for humans; a line with a support link may be appended, so do not compare the message as a whole.

The gateway returns this error itself without forwarding the request to the provider, so such a request is not billed.

Do not confuse it with similar errors:

The list of enabled models

GET https://api.zukko.pro/v1/models is a public endpoint that needs no key. It returns only the models enabled right now:

curl -s https://api.zukko.pro/v1/models

{
  "object": "list",
  "data": [
    {"id": "claude-sonnet-5", "object": "model", "created": 1700000000, "owned_by": "zukko"},
    {"id": "gpt-5.6-sol", "object": "model", "created": 1700000000, "owned_by": "zukko"},
    {"id": "glm-5.3-flash", "object": "model", "created": 1700000000, "owned_by": "zukko"}
  ]
}

IDs only, if you have jq:

curl -s https://api.zukko.pro/v1/models | jq -r '.data[].id'

The same list is on the "Models" page in the dashboard. The endpoint is described in the models reference↗.

How to choose a replacement

We do not make claims like "this model is as good as that one": test quality on your own tasks. But there are formal criteria a replacement must meet:

• Context. If you send more than 128K tokens, only 1M-context models fit: claude-opus-5-5, claude-sonnet-5, gpt-5.6-sol, gpt-5.6-luna.
• Endpoint. Via /v1/responses (for example, in Codex) Claude and GPT models work, GLM does not.
• Price. Check the price table: the replacement may cost more than your primary model.
• Key. If the key has an allowed-models list, the replacement must be in it, or you get 403 model_not_allowed_for_key.

Any model can be called in either OpenAI or Anthropic format, since the gateway converts the request, so you do not need to change clients to switch models.

Code with a fallback model

An OpenAI SDK example: a preference list, a 5-minute cache of enabled models, and moving to the next model on model_disabled. The primary model is tried first on every call, so once it is enabled again, the code returns to it automatically.

import os
import time

import openai
from openai import OpenAI

client = OpenAI(
    base_url="https://api.zukko.pro/v1",
    api_key=os.environ["OPENAI_API_KEY"],
    max_retries=0,
)

PREFERRED = ["claude-sonnet-5", "gpt-5.6-sol", "claude-opus-5-5"]
_cache = {"models": set(), "at": 0.0}

Notes:

• max_retries=0 turns off the SDK's built-in retries: retrying a request to a disabled model is pointless.
• error_code pulls code out of the error body; it also works with Anthropic SDK exceptions.
• If you use the Anthropic SDK, its base URL is https://api.zukko.pro without /v1, and the logic stays the same. See the Python SDK guide↗.
• Log which model actually answered: if a fallback model is serving traffic, you want to see that in monitoring.

Claude Code: switching the model

Claude Code connects to Zukko via ANTHROPIC_BASE_URL=https://api.zukko.pro and ANTHROPIC_AUTH_TOKEN=fetch_.... You can change the model in three ways:

• inside a session with /model claude-sonnet-5;
• at launch: claude --model claude-sonnet-5;
• with an environment variable before launch:

export ANTHROPIC_MODEL=claude-sonnet-5
claude

If the model is set in an environment variable or in settings, update the value once that model is disabled, or every session will start with an error. Full setup is in the Claude Code guide↗.

Cursor and other IDEs

In Cursor, a model connected through Zukko is set by name in the model settings. If it is disabled, add or select another model from GET /v1/models with the same key and the base URL https://api.zukko.pro/v1. Cursor's menu labels change between versions, so check our Cursor guide↗ and the editor's own documentation. In Cline, Roo Code and Kilo Code it is the same: change the model ID field in the provider settings.

FAQ

How often are models disabled, and for how long?

That cannot be predicted in advance. So it is wise not to hard-code a single model without a fallback, and to check GET /v1/models before choosing. Service news is posted in the Telegram channel @zukkopro↗.

Will my app stay on the fallback model forever?

Not with the example above: the primary model is first in PREFERRED and is tried on every call as soon as it reappears in the enabled list (the cache refreshes every 5 minutes or right after an error).

Am I charged for a request that fails with model_disabled?

No. The gateway returns this error itself without sending the request to the provider, so no tokens are used.

What if every model on my list is disabled?

The example code then raises a clear exception. What happens next depends on your app: queue the task and retry later, show the user a message, or extend PREFERRED with models that fit your context and format needs. If your key is restricted to a list of models, remember to add the new ones there too on the keys page↗.