UnlimGPT

Разбирайте ошибки и лимиты API

Прочитайте публичный код ошибки и ID запроса перед решением о повторе.

Сначала прочитайте HTTP-статус, публичный код ошибки, заголовок request-id и, если они есть, retry-after и x-should-retry. OpenAI-совместимые endpoint возвращают объект error; Messages — конверт формата Anthropic. Для диагностики можно сохранить время, endpoint, публичный ID модели и эти безопасные значения. API-ключ, prompt, response, cookie браузера и сырую внутреннюю ошибку не помещайте в логи и обращения в поддержку.

Читайте код, а не только HTTP-статус

Ответы OpenAI-совместимых операций содержат error.message, error.type, error.code и request_id. Для Messages конверт содержит type: "error", вложенные error.type и error.message, а также request_id. Заголовки request-id и x-request-id помогают сопоставить ответ с обращением в поддержку. Клиенту лучше принимать решение по HTTP-статусу, публичному коду и заголовкам повтора; текст message предназначен человеку и может меняться.

Можно передать UUID в x-request-id: Gateway сохраняет его либо генерирует новый при отсутствии или неверном формате. Терминальные ошибки потока содержат тот же request_id на верхнем уровне Responses response.failed, Messages error и объекта ошибки Chat Completions. Это ID HTTP-запроса; поле id ответа или чанка по-прежнему обозначает логический ответ. При повторе неуспешного результата по ключу идемпотентности тело сохраняет ID исходного запроса, а HTTP-заголовки обозначают новый запрос повтора. Для поддержки используйте прежде всего ID из тела.

В Responses response.failed.code содержит публичный код UnlimGPT, а response.error.code сохраняет категорию ошибки для SDK.

Например, временная недоступность модели на Responses возвращает HTTP 503 и безопасный код provider_unavailable:

json
{
  "error": {
    "message": "The model is temporarily unavailable.",
    "type": "server_error",
    "param": null,
    "code": "provider_unavailable"
  },
  "request_id": "01992b95-663e-76e2-8f05-3ff3363c5f90"
}

ID в примере приведён только для показа формата: сохраняйте ID из собственного ответа. Messages для того же кода использует error.type: "overloaded_error". Наличие HTTP 503 не гарантирует безопасный повтор — проверьте x-should-retry, retry-after и исход логического запроса.

При ограничении частоты читайте x-ratelimit-limit-requests, x-ratelimit-remaining-requests и x-ratelimit-reset-requests. Anthropic-совместимые клиенты получают те же значения в семействе anthropic-ratelimit-requests-*; формат момента сброса у них отличается. Эти заголовки описывают лимит запросов организации. Для долгого лимита подписки OpenAI-совместимый ответ может дополнительно передать error.resets_at вместе с retry-after.

Проверьте причину безопасно

Бесплатный каталог моделей позволяет проверить авторизацию и видимость модели до повторной платной генерации. Убедитесь, что ключ относится к выбранной организации и имеет права, показанные в API-ключах. Если ошибка возникла в потоке, прочитайте его последнее событие: после начального HTTP 200 ещё может прийти терминальная ошибка. Пока исход неясен, храните ключ идемпотентности и неизменное тело запроса.

Выберите действие

  • HTTP 401 authentication_required: проверьте Bearer-заголовок, состояние ключа и срок действия по авторизации. Сессия браузера не заменяет API-ключ.
  • HTTP 400 invalid_request: исправьте формат JSON, несовместимые поля или содержимое запроса. Для отсутствующего ресурса этот код может сопровождаться HTTP 404; проверяйте оба значения.
  • HTTP 402 insufficient_credits: посмотрите кредиты и лимиты. Дождитесь подходящего гранта или измените состояние аккаунта перед новым платным запросом.
  • HTTP 403 early_access_required или permission_denied: проверьте доступ организации и права ключа. Смена модели не выдаст недостающий доступ аккаунту.
  • HTTP 403 account_suspended: доступ к аккаунту приостановлен. Сохраните ID запроса для поддержки; повтор или другой ключ не устранит ограничение.
  • HTTP 404 model_not_found: выберите канонический ID из каталога, а не отображаемое имя или предполагаемый ID.
  • HTTP 404 not_found: проверьте адрес endpoint и публичный ID операции; чужой или неизвестный запуск не раскрывается.
  • HTTP 409 idempotency_conflict: следуйте процедуре повтора. Повтор допустим только при x-should-retry: true и неизменном теле.
  • HTTP 413 request_too_large: уменьшите тело до 4 МиБ с учётом закодированных медиафайлов.
  • HTTP 429 rate_limit_exceeded, concurrency_limit_exceeded или usage_limit_exceeded: проверьте retry-after и x-should-retry. Частотный и параллельный лимиты могут разрешить повтор после паузы; лимит пакета требует обновления окна или смены тарифа.
  • unsupported_capability или context_length_exceeded: уберите неподдерживаемую возможность или сократите ввод перед новым логическим запросом.
  • HTTP 503 provider_unavailable: модель временно недоступна. Сохраните ID запроса и проверьте доступность модели; при разрешённом повторе используйте тот же ключ идемпотентности и тело.
  • HTTP 504 generation_timeout: логический запрос превысил срок исполнения. Проверьте терминальный исход и активность перед повтором, чтобы не запустить вторую генерацию.
  • HTTP 500 internal_error: сохраните ID запроса для поддержки; при x-should-retry: false автоматический повтор запрещён.
  • request_cancelled: клиент или пользователь отменил операцию; соединение может закрыться без нового HTTP-ответа. Это терминальный исход, а не повод автоматически повторять платную генерацию.

x-should-retry: false запрещает автоматический повтор той же операции. При true выдержите retry-after и сохраните прежние Idempotency-Key и тело запроса. Отсутствие этого заголовка само по себе не разрешает бесконечные повторы: ограничьте число попыток и общий дедлайн клиента. Для потоков смотрите нативное терминальное событие, поскольку HTTP 200 фиксирует только начало передачи.

Подтвердите восстановление

После исправления причины отправьте один ограниченный запрос к модели из каталога. Успешный запрос без потока имеет завершённый ответ; для SSE нужно дождаться нативного терминального события. Если исход остаётся неясным, сопоставьте активность API той же организации по времени и endpoint, а поддержке передайте только публичный ID запроса и безопасный код. При сбоях транспорта используйте диагностику подключения. Контекст протоколов есть в руководствах Responses, Chat Completions и Messages.