Ошибки API

Справочник API

Zukko отвечает на ошибки обычным HTTP-статусом и JSON-телом в формате OpenAI. Разбирайте ошибку по status и error.code, а не по тексту: текст собственных ошибок Zukko на русском и может меняться.

1Формат ошибки

json

{
  "error": {
    "message": "Модель 'gpt-5.4' снята с обслуживания. Используйте 'gpt-5.6-sol' — актуальный список: GET /v1/models. Поддержка — https://t.me/zukkopro?direct, напишите, пожалуйста.",
    "type": "invalid_request_error",
    "code": "model_retired",
    "param": "model"
  }
}

error.message есть всегда;
error.code — у всех ошибок Zukko, кроме 401;
error.type и error.param — там, где применимо.

К каждому сообщению об ошибке в конце дописывается строка поддержки: «Поддержка — https://t.me/zukkopro?direct, напишите, пожалуйста.» У 401 есть ещё поле верхнего уровня "type": "error" и error.type: "authentication_error". У 403 email_unverified поля message и code продублированы и на верхнем уровне.

2Коды ошибок

Статус	Код	Когда	Повторять?
400	`model_retired`	модель снята с обслуживания; в сообщении — на какую перейти	нет, смените модель
400	`invalid_json`	тело не JSON (GLM, веб-поиск, изображения)	нет, исправьте запрос
400	`invalid_request`	веб-поиск без `query`	нет
400	`invalid_request_error`	изображения: нет `prompt` или `images` для edit-модели	нет
400	`unknown_glm_model`	неизвестная модель GLM	нет
401	— (`authentication_error`)	ключа нет, он с опечаткой или отозван	нет
402	`insufficient_balance`	на балансе меньше $0.01 (для изображений — меньше цены картинки)	после пополнения
403	`email_unverified`	email не подтверждён	после подтверждения
403	`model_not_allowed_for_key`	модели нет в списке разрешённых для этого ключа	нет
404	`model_not_found`	модели нет в каталоге; запрос не уходит к провайдеру и не оплачивается	нет, исправьте имя по `GET /v1/models`
404	`not_found`	несуществующий путь	нет
405	`method_not_allowed`	неверный HTTP-метод	нет
413	`payload_too_large`	тело запроса больше 32 МБ	нет, уменьшите запрос
422	`idempotency_conflict`	`Idempotency-Key` уже использован с другим телом	нет, новый ключ
429	`key_daily_limit_reached`	исчерпан дневной лимит ключа	после 00:00 UTC или поднимите лимит
429	`key_monthly_limit_reached`	исчерпан месячный лимит ключа	с нового месяца (UTC) или поднимите лимит
429	код провайдера	лимит на стороне провайдера модели	да, с паузой
502	`upstream_unreachable`	провайдер модели не ответил	да, с паузой
502	`web_search_failed`	веб-поиск не выполнился	да
502	`image_generation_failed`	генерация изображения не удалась	да
503	`model_disabled`	модель временно выключена	нет, возьмите другую из `GET /v1/models`
503	`provider_unavailable`	провайдер модели временно недоступен	да, с паузой или другой моделью
503	`maintenance`	технические работы, есть заголовок `Retry-After: 600`	да, через `Retry-After` секунд
503	`image_provider_unavailable`, `image_provider_busy`	сервис изображений недоступен или перегружен	да, позже
504	`image_generation_timeout`	генерация изображения заняла больше 3 минут	да

Собственного ограничения частоты запросов у Zukko нет. 429 от Zukko — это только лимиты ключа, которые вы задали сами. Любой другой 429 пришёл от провайдера модели.

3Ошибки провайдера

Ошибки, которые вернул провайдер модели, Zukko отдаёт с тем же статусом и текстом — например, превышение контекста или неверный параметр. Исключения:

если провайдер ответил 402, клиент получает 503 provider_unavailable — это не ваш баланс;
если текст ошибки ничего не объясняет, Zukko заменяет его своим: для 5xx — «Провайдер модели временно недоступен, повторите запрос позже», для 4xx — «Провайдер модели отклонил запрос, проверьте параметры»;
к ошибкам 5xx Zukko дописывает список моделей, которые сейчас работают.

500 с телом {"error": "Internal server error"} означает сбой на стороне Zukko — повторите запрос и, если не помогло, напишите в поддержку.

4Ошибки внутри потока

При stream: true статус 200 приходит раньше, чем ответ модели. Если ошибка случилась уже после этого, она придёт внутри потока событием с полем error. Проверяйте события потока, а не только HTTP-статус. Поток, в котором была только ошибка — без текста и без usage, — не оплачивается. Подробнее — Стриминг.

5Как повторять запросы

повторяйте 429 от провайдера, 500, 502, 503 (кроме model_disabled) и 504 с экспоненциальной паузой;
при 503 maintenance ждите столько секунд, сколько указано в Retry-After;
остальные 4xx не повторяйте — исправьте запрос, ключ или баланс;
добавляйте заголовок Idempotency-Key: повтор уже выполненного запроса вернёт сохранённый ответ и не спишет деньги второй раз. Отправляйте повтор после того, как первый запрос завершился, — см. идемпотентность.

Аутентификация

Стриминг