Разберите неудачный запрос

Начните с HTTP-статуса, публичного кода ошибки, заголовка request-id и времени вызова. Не вставляйте API-ключ, prompt, response или сырой текст внутренней ошибки в обращение.

Читайте форму ошибки своего протокола: OpenAI- и Anthropic-совместимые API оформляют её по-разному, но безопасный публичный код подсказывает следующее действие. Сохраните заголовки ответа до повтора. Если ответа вообще не было, сначала откройте проверки подключения: отсутствие ответа не равно отказу API.

Проверьте причину

1. При 401 authentication_required проверьте Bearer- или Anthropic-заголовок, состояние и срок ключа. При 403 permission_denied либо early_access_required проверьте организацию, доступ тарифа и права ключа по руководству авторизации. Не делайте платный вызов только ради проверки ключа.
2. При 402 insufficient_credits проверьте подходящие кредиты и лимиты. Пополнение не оплатит исполнение Jailbreak, доступного лишь по подписке. При 429 отличайте временный rate_limit_exceeded от usage_limit_exceeded и соблюдайте Retry-After и x-should-retry.
3. При 404 model_not_found выберите действительный ID из бесплатного каталога моделей, а не отображаемое имя. При 413 request_too_large уменьшите тело запроса или медиа до повтора.
4. При unsupported_capability, context_length_exceeded либо invalid_request сначала исправьте неподдерживаемую возможность, объём контекста или ошибочное поле. Ограничения указаны в руководствах API и возможностях выбранной модели. Неизменённое тело не станет допустимым при повторе.
5. При 409 idempotency_conflict сравните параметры с исходным Idempotency-Key. Дублирующий запрос, который ещё выполняется, можно повторить после рекомендованной паузы с тем же ключом и телом; несовпадение параметров нужно исправить.
6. Если SSE-поток начался с HTTP 200, прочитайте терминальное событие. Поздняя ошибка всё равно означает неудачный запуск. Начальный 200 сам по себе не доказывает завершение или списание.

Повторяйте без лишней генерации

Перед повтором после таймаута или обрыва потока прочитайте идемпотентность и повторы. Для того же логического запроса используйте прежний Idempotency-Key и те же нормализованные параметры в течение его 24-часового окна. Не запускайте новый платный запрос только из-за обрыва сети: первый может ещё выполняться. При x-should-retry: false исправьте причину либо дождитесь объявленного обновления лимита, не создавая цикл.

Если запрос вообще не доходит до сервиса, откройте проверки подключения. Doctor нужен для проблемы клиента или авторизации. Для обращения в поддержку сохраните время по UTC, endpoint, публичный ID модели при необходимости, статус, безопасный код ошибки, признак потока и заголовок request-id либо x-request-id. Для начала достаточно публичного ID и кода; не прикладывайте тело, секрет или полный дамп окружения. В активности API можно найти недавнюю операцию, но её ID не следует приравнивать к HTTP ID запроса.