Ошибки

Конверт

Каждый сбой, независимо от статуса, — это один JSON-объект:

{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient balance",
    "request_id": "7f20a5f0-5dde-48cf-94aa-38acbbd218e0"
  }
}

code стабилен и рассчитан на машинную обработку. Ветвите логику по нему, а не по message.
message — пояснение для человека, оно может меняться.
request_id — UUID запроса. Он также возвращается в заголовке X-Request-ID в каждом ответе, успешном или нет. Указывайте его, когда сообщаете о проблеме.

На потоковом эндпоинте сбой, случившийся после начала стрима, приходит как событие error с теми же тремя полями; см. Стриминг.

Коды

HTTP	Код	Значение
401	`invalid_api_key`	Ключ отсутствует, некорректен, неизвестен, удалён или у него неверный секрет
403	`agent_mismatch`	Ключ принадлежит другому агенту
403	`permission_denied`	Ключ с `read-only` вызвал эндпоинт чата
403	`agent_disabled`	Агент выключен. Только эндпоинты чата
404	`agent_not_found`	Агента больше не существует. Только эндпоинты чата
404	`conversation_not_found`	Неизвестный диалог или диалог не этого ключа
402	`insufficient_balance`	Баланс владельца не покрывает ответ; ничего не списано
409	`idempotency_conflict`	Тот же `Idempotency-Key` использован с другим телом
409	`idempotency_in_progress`	Исходный запрос ещё выполняется; повторите через `Retry-After` секунд (всегда `2`)
409	`conversation_busy`	Другое сообщение того же внешнего пользователя сейчас обрабатывается; повторите через `Retry-After` (всегда `2`)
422	`validation_error`	Некорректное тело, заголовок, дата, лимит или курсор
429	`rate_limit_exceeded`	Окно ключа исчерпано; см. Лимиты запросов
503	`api_rate_limit_unavailable`	Ограничитель недоступен; запрос отклонён, а не обслужен без учёта. Повторите через `Retry-After` (всегда `5`)
503	`service_unavailable`	Недоступен бэкенд, от которого зависит API; повторите через `Retry-After` (всегда `2`)
500	`internal_error`	Непредвиденный сбой; укажите `request_id`

agent_not_found и agent_disabled проверяются только в POST …/chat и POST …/chat/stream. Два GET-эндпоинта не смотрят на состояние агента: ключ выключенного агента всё ещё может получить список его диалогов и прочитать сообщения.

Что повторять

Повторить через Retry-After с тем же Idempotency-Key

idempotency_in_progress, conversation_busy, rate_limit_exceeded, api_rate_limit_unavailable, service_unavailable. Повторное использование ключа гарантирует, что вы никогда не заплатите дважды за одно сообщение.

Сначала исправить запрос

validation_error (прочитайте message; в нём названо проблемное поле), idempotency_conflict (используйте новый ключ для нового тела), permission_denied (используйте ключ с full), agent_mismatch (используйте агента, которому принадлежит ключ).

Не повторять автоматически

invalid_api_key (ключ удалён или секрет неверен), agent_disabled, agent_not_found, insufficient_balance (сначала пополните баланс). Цикл повторов на этих кодах только сжигает лимит запросов.

Сообщить с идентификатором запроса

internal_error. Повторите один раз с тем же Idempotency-Key: неуспешная запись освобождается, поэтому повтор выполняет запрос заново, а не воспроизводит сохранённый результат. Это ожидаемо, но не гарантирует бесплатность. Если сбой случился после того, как модель уже ответила, повтор создаст новый ответ и новое списание. Если сбой повторяется, пришлите нам request_id.

Замечание о 401

API не различает удалённый ключ и ключ, которого никогда не было: оба — invalid_api_key. Если ключ, который раньше работал, начал возвращать 401, проверьте карточку «Доступ по API» в приложении; скорее всего, его обновили или удалили.

Начало работы

Руководства

Конверт

Коды

Что повторять

Замечание о 401

​Конверт

​Коды

​Что повторять

​Замечание о 401

Конверт

Коды

Что повторять

Замечание о 401