401, 402, model not found: разбор ошибок подключения к API

Подключение к совместимому API обычно занимает пару минут, а когда не занимает — причина почти всегда в одном из четырёх мест. Ниже — как читать ответ сервера и что чинить.

401 — ключ не принят

{"error": {"message": "Unauthorized", "type": "authentication_error"}}

Что проверить по порядку.

Пробелы вокруг ключа. При копировании из мессенджера часто прилипает пробел или перенос строки. Ключ должен идти сразу после Bearer .

Имя переменной. У Claude Code это ANTHROPIC_AUTH_TOKEN, а не ANTHROPIC_API_KEY — со вторым он считает, что вы работаете через официальный аккаунт, и просит логин. У Codex ключ ищется в ~/.codex/auth.json под именем OPENAI_API_KEY независимо от провайдера.

Ключ отозван. Ключи показываются один раз при создании. Если сомневаетесь, что сохранили правильный, выпустите новый — это дешевле, чем гадать.

Валидный JSON. В settings.json лишняя запятая в конце тихо ломает весь файл, и переменные просто не доезжают.

402 — пустой баланс

{"error": {"message": "Недостаточно средств на балансе", "code": "insufficient_balance"}}

Самая честная из ошибок: денег на счету нет, запрос до модели не пошёл. Пополните баланс и повторите — перезапускать инструмент не нужно.

Полезно знать, что проверка баланса происходит до обращения к провайдеру, поэтому неудачный запрос ничего не стоит.

404 — почти всегда лишний или недостающий /v1

Это самая частая ошибка первого подключения, и она не про ключ.

Anthropic-совместимые клиенты — Claude Code, Anthropic SDK, Roo Code — идут на адрес без суффикса: https://api.zukko.pro. Они добавляют путь сами.

OpenAI-совместимые — Cursor, Codex, Cline, OpenAI SDK — идут с суффиксом: https://api.zukko.pro/v1.

Если перепутать, каждый запрос будет уходить на несуществующий путь. Симптом характерный: ключ принимается, но любой вызов возвращает 404.

Модель не найдена

{"error": {"message": "The model 'gpt-4o' does not exist", "code": "model_not_found"}}

Название не совпадает с каталогом. Регистр и точки в номере версии значимы: claude-sonnet-5, а не Claude-Sonnet-5 и не claude sonnet 5.

Актуальный список доступен без ключа:

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

Отдельный случай — модель сняли с обслуживания. Тогда ответ прямо называет замену:

{"error": {
  "message": "Модель 'gpt-5.4' снята с обслуживания. Используйте 'gpt-5.6-terra'",
  "code": "model_retired"
}}

Это не ошибка настройки: каталог обновился, и в конфиге остался старый идентификатор.

Запрос уходит, но ничего не происходит

Если инструмент молчит, проверьте, что он вообще ходит по вашему адресу, а не по адресу провайдера по умолчанию. В Claude Code достаточно задать любой вопрос — первый же ответ подтвердит, что биллинг идёт с вашего баланса, потому что расход появится в истории кабинета.

Быстрая проверка связи

Прежде чем разбираться в конфигах инструмента, убедитесь, что ключ работает сам по себе:

curl https://api.zukko.pro/v1/messages \
  -H "Authorization: Bearer fetch_ваш_ключ" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-sonnet-5","max_tokens":64,"messages":[{"role":"user","content":"привет"}]}'

Если ответ пришёл — проблема в настройках инструмента, а не в доступе. Если нет — ошибка из ответа скажет, что именно чинить.

Ключ выдаётся в кабинете, стартовый доллар на проверку начисляется при первом входе в @zukkopro_bot↗.