Коды ошибок API Claude, Codex, GLM и Kimi: полное руководство по устранению неполадок

При интеграции Claude, Codex, GLM, Kimi или других больших языковых моделей в приложение ошибки API неизбежны. Запрос, который вчера работал безупречно, может внезапно вернуть 400 Bad Request, 429 Too Many Requests или 502 Bad Gateway, и сообщение об ошибке, отображаемое клиентом, не всегда объясняет, что на самом деле пошло не так.

Ситуация становится ещё более сложной, когда разработчики используют API-шлюз или сервис-ретранслятор. Запрос не обязательно проходит напрямую от приложения к провайдеру модели. Вместо этого он может проходить через несколько слоёв, отвечающих за аутентификацию, маршрутизацию моделей, выбор аккаунта, преобразование протокола, ограничение частоты запросов и переключение на резервный upstream при сбоях.

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

В этом руководстве рассматриваются наиболее распространённые ошибки Claude API, ошибки Codex API, ошибки GLM API и ошибки Kimi API, включая 400, 401, 403, 404, 408, 429, 500, 502, 503 и 504. Также объясняется, почему ошибка 502 не обязательно означает, что сам API-шлюз неисправен, как определить реальную upstream-ошибку и что разработчики могут сделать для решения этих проблем.

Как на самом деле работает запрос к AI API

Прежде чем приступать к устранению ошибки API, полезно понять полный путь запроса.

Типичный прямой API-запрос выглядит так:

Your Application
      ↓
AI Provider API
      ↓
Claude / Codex / GLM / Kimi

При использовании API-шлюза или платформы-ретранслятора архитектура становится сложнее:

Your Application
      ↓
API Gateway
      ↓
Authentication
      ↓
Model / Group Routing
      ↓
Channel Selection
      ↓
Upstream Account
      ↓
AI Provider
      ↓
Claude / Codex / GLM / Kimi

Каждый слой может привнести свой собственный тип сбоя.

Например, недействительный ключ API может сгенерировать 401 ещё до того, как запрос достигнет провайдера модели. Некорректно сформированный запрос может привести к 400 во время преобразования протокола. Ограничение квоты на стороне провайдера может вызвать 429, а сбой upstream-запроса может быть представлен клиенту как 502.

Именно поэтому одного кода состояния HTTP часто недостаточно.

Краткий справочник: распространённые коды ошибок AI API

Самое важное различие — между ошибками запроса на стороне клиента и ошибками upstream-инфраструктуры.

400 Bad Request: проверьте запрос, прежде чем винить модель

Ошибка 400 Bad Request обычно означает, что сервер получил запрос, но не смог его обработать, поскольку что-то в запросе было недопустимым или неподдерживаемым.

Для API Claude, Codex, GLM и Kimi распространённые причины включают недопустимое имя модели, неподдерживаемые параметры, некорректно оформленные вызовы инструментов, некорректно сформированную историю сообщений или несовместимость протоколов.

Это особенно часто встречается, когда разработчики используют OpenAI-совместимые API, поскольку разные провайдеры не обязательно поддерживают в точности одинаковую схему запроса.

Например, клиент может отправить:

{
  "model": "gpt-5.5",
  "metadata": {},
  "input": [...]
}

Публичный API может поддерживать metadata, тогда как внутренний upstream-эндпоинт, используемый шлюзом, может отклонить его. Недавний issue в Sub2API документировал именно такую ситуацию: параметр metadata был переслан на upstream-эндпоинт Codex, который не принимал это поле, что привело к upstream-ошибке 400, которую Sub2API затем представил как 502.

Другой issue в Sub2API документировал пересылку неподдерживаемого параметра user через /v1/responses, что снова вызвало upstream-ошибку 400.

Решение обычно состоит в том, чтобы проверить запрос на соответствие фактической схеме upstream API, а не предполагать, что каждый OpenAI-совместимый эндпоинт поддерживает каждый параметр OpenAI.

При отладке 400 начните с имени модели, эндпоинта, параметров запроса, определений инструментов, полей thinking или reasoning, истории сообщений и формата протокола.

Ошибки 400 в Claude API: проблемы с thinking и signature

Рабочие процессы кодирования на основе Claude могут привносить ещё один класс ошибок 400, связанных с блоками thinking и подписями.

Недавний issue в Sub2API сообщал:

API Error: 400

Invalid `signature` in `thinking` block

Тот же самый запрос затем мог выдать клиенту обобщённое сообщение Upstream request failed.

Этот тип ошибки особенно актуален для Claude Code и приложений в стиле агентов, поскольку разговоры больше не являются простыми последовательностями пользовательских сообщений и текста ассистента. Запрос может содержать блоки thinking, вызовы инструментов, результаты инструментов и другое структурированное содержимое.

Если прокси или шлюз изменяет, отбрасывает или некорректно реконструирует часть этого состояния разговора, upstream-модель может отклонить запрос.

По этой причине, когда Claude Code внезапно начинает возвращать ошибки 400 во время многошаговых задач, разработчикам следует проверить, возникает ли проблема только при использовании thinking, инструментов или длительных разговоров, а не сразу предполагать, что ключ API истёк.

401 Unauthorized: проверьте свой ключ API

Ошибка 401 обычно означает, что сервер не смог аутентифицировать запрос.

Первое, что нужно проверить, — заголовок Authorization:

Authorization: Bearer YOUR_API_KEY

Если вы используете Claude, Codex, GLM или Kimi через шлюз, убедитесь, что вы используете ключ API шлюза, а не учётные данные upstream-провайдера.

Это различие имеет значение, поскольку запрос может иметь два совершенно разных слоя аутентификации:

Client API Key
      ↓
Gateway
      ↓
Upstream Account

Действительный upstream-аккаунт не обязательно означает, что ключ API на стороне клиента действителен.

Если все модели возвращают 401, сначала проверьте конфигурацию клиента. Если только одна группа или модель возвращает 401, исследуйте конфигурацию канала или upstream-аккаунта шлюза.

403 Forbidden: аутентификация работает, а прав нет

403 отличается от 401.

При 401 сервер не принимает вашу аутентификацию.

При 403 запрос может быть аутентифицирован, но пользователь, ключ API, аккаунт, модель или канал не имеет прав на выполнение операции.

Например, шлюз может разрешить пользователю вызывать Claude Sonnet, но не какую-то конкретную премиум-модель. Канал также может быть настроен для определённой группы, тогда как другая модель недоступна.

Если разработчик сообщает:

«Мой ключ API работает, но эта конкретная модель возвращает 403.»

то первое, что нужно проверить, — доступность модели, конфигурацию группы, права аккаунта и ограничения провайдера.

Не создавайте сразу же новый ключ API.

404 Not Found: проблема с эндпоинтом или моделью

404 обычно означает, что запрашиваемый ресурс не существует.

В AI-приложениях это может означать несколько вещей.

Эндпоинт может быть неверным:

/v1/chat/completions

в сравнении с:

/v1/responses

Модель может не существовать в выбранной группе, или upstream-провайдер может не предоставлять запрашиваемый эндпоинт.

Это особенно важно для новых моделей, поскольку имена моделей и совместимость эндпоинтов могут меняться.

При устранении 404 проверьте Base URL, эндпоинт, имя модели, провайдера и конфигурацию канала.

Полезный тест — вызвать простейший поддерживаемый эндпоинт с максимально простым запросом, прежде чем тестировать продвинутые возможности, такие как инструменты, reasoning, генерация изображений или потоковая передача.

429 Too Many Requests: ограничение частоты или квота?

429 — одна из самых распространённых ошибок, с которыми сталкиваются разработчики при работе с AI API.

Очевидная интерпретация такова:

Слишком много запросов.

Но на практике 429 может представлять несколько разных ограничений.

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

Именно поэтому снижения частоты запросов не всегда достаточно.

Предположим, кодирующий агент генерирует большой объём контекста и отправляет несколько запросов одновременно. Даже если количество запросов невелико, приложение всё равно может достичь ограничения на основе токенов.

Поэтому процесс устранения проблемы должен учитывать:

Для приложений с большим объёмом трафика может также помочь логика повторных попыток с экспоненциальной задержкой. Однако многократные немедленные повторы запроса могут усугубить ситуацию, увеличив нагрузку.

500 Internal Server Error: что-то дало сбой на сервере

500 обычно означает, что сервер столкнулся с непредвиденной внутренней ошибкой.

При использовании API-шлюза важно определить, пришла ли ошибка 500 от шлюза или от upstream-провайдера.

Если ошибку сгенерировал сам шлюз, администраторам следует проверить логи приложения, подключение к базе данных, Redis, конфигурацию каналов, выбор аккаунта и недавние изменения при развёртывании.

Если upstream-провайдер вернул 500, шлюз может просто пересылать или оборачивать сбой upstream.

Поэтому для клиентов наиболее полезной информацией является не только:

500 Internal Server Error

но также связанный идентификатор запроса, модель, канал и временная метка.

502 Bad Gateway: ошибка, которую разработчики понимают неправильнее всего

502 заслуживает особого внимания, поскольку она чрезвычайно распространена в архитектурах API-шлюзов.

Многие разработчики видят:

502 Bad Gateway

и сразу заключают:

«API-шлюз не работает.»

Это не обязательно так.

Шлюз может вернуть 502, потому что он успешно получил запрос, но не смог получить действительный ответ от upstream-сервиса.

Упрощённая цепочка запросов выглядит так:

Client
  ↓
Gateway
  ↓
Upstream
  ↓
400
  ↓
Gateway
  ↓
502
  ↓
Client

Это поведение неоднократно документировалось в issue Sub2API.

Например, недавний issue показал upstream-ошибку 400, вызванную неподдерживаемым параметром background, тогда как клиент получил лишь:

502 Upstream request failed

Фактическая причина была видна в логах шлюза как upstream 400 Unsupported parameter: background.

Другой issue касался запросов OpenAI Responses API, содержащих системные сообщения в неподдерживаемой форме. Upstream отклонил запрос, а Sub2API вернул клиенту 502 Bad Gateway.

Поэтому 502 следует рассматривать как сигнал к проверке upstream-ошибки, а не как окончательный диагноз.

Codex и Responses API: почему 502 может стать сложной

Рабочие процессы в стиле Codex могут особенно затруднить устранение проблем со шлюзом, поскольку Responses API поддерживает stateful- и многошаговые взаимодействия.

Например, issue в Sub2API документировал ситуацию, когда одна и та же логическая сессия Codex маршрутизировалась между разными upstream-аккаунтами OpenAI. Зашифрованный контекст, сгенерированный одним аккаунтом, не мог быть верифицирован другим аккаунтом, из-за чего upstream возвращал 400, а шлюз возвращал 502.

Архитектура выглядела примерно так:

Codex Session
     ↓
Gateway
     ↓
Account A
     ↓
Encrypted Context
     ↓
Retry
     ↓
Account B
     ↓
Cannot decrypt context
     ↓
Upstream 400
     ↓
Gateway 502

Это иллюстрирует, почему простая случайная ротация аккаунтов не всегда подходит для stateful-API.

Для приложений, использующих Codex, Responses API, зашифрованный контекст, вызовы инструментов или многошаговые сессии, шлюзу может потребоваться привязка к сессии (session affinity), чтобы связанные запросы оставались привязаны к совместимому upstream-аккаунту.

502 также может быть вызвана состоянием разговора

Другой недавний issue в Sub2API касался повторно воспроизведённых элементов reasoning в многошаговых запросах Responses API. Upstream вернул 404, поскольку упомянутый элемент reasoning был больше недоступен, а шлюз представил сбой как 502.

Это ещё одна причина, по которой разработчикам не следует рассматривать 502 как обобщённую сетевую ошибку.

Основная проблема на самом деле может быть:

400 Invalid Parameter

или:

404 Missing Conversation Item

или:

Authentication Failure

или:

Upstream Timeout

Задача шлюза — взаимодействовать с upstream-провайдером, и то, как именно upstream-ошибка представляется, зависит от реализации шлюза.

503 Service Unavailable

503 обычно указывает на то, что сервис временно недоступен.

Это может произойти, когда upstream-провайдер испытывает сбой, шлюз временно отключил канал или в настоящий момент нет пригодного к использованию аккаунта.

Для шлюза с несколькими аккаунтами важно различать, что именно:

One account → unavailable

или:

Entire channel → unavailable

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

Если сбоят все аккаунты, проблема, скорее всего, связана с провайдером, каналом или инфраструктурой.

504 Gateway Timeout

504 Gateway Timeout обычно означает, что шлюз ждал ответа от upstream, но не получил его в течение настроенного таймаута.

Это особенно часто встречается при длительных AI-запросах.

Крупные задачи reasoning, генерация кода, генерация изображений, вызовы инструментов и запросы с длинным контекстом естественным образом могут занимать больше времени, чем обычный веб-запрос.

Решение может включать увеличение upstream-таймаута, улучшение поведения потоковой передачи, проверку задержки провайдера или смену модели или канала.

Разработчикам следует быть осторожными и не рассматривать каждый таймаут как сбой модели. Иногда запрос всё ещё обрабатывается upstream, тогда как шлюз уже перестал ждать.

Практический процесс устранения ошибок

Когда API-запрос завершается сбоем, не начинайте со случайной смены ключей API, моделей или конфигурации.

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

Начните с кода состояния HTTP, затем прочитайте полное сообщение об ошибке. Далее определите, возникла ли ошибка на стороне клиента, шлюза или upstream-провайдера.

Следующая схема хорошо подходит для большинства проблем с API Claude, Codex, GLM и Kimi:

API Request Failed
       ↓
Check HTTP Status
       ↓
Is it 401 / 403?  → Check API Key / Permission
Is it 400?        → Check Parameters / Protocol / Model
Is it 404?        → Check Endpoint / Model / Resource
Is it 429?        → Check Quota / RPM / TPM / Concurrency
Is it 500?        → Check Gateway / Provider Logs
Is it 502?        → Check Upstream Error
Is it 503 / 504?  → Check Provider / Channel / Timeout

Для операторов шлюзов наиболее полезная отладочная информация обычно включает идентификатор запроса, модель, эндпоинт, канал, upstream-аккаунт, upstream-код состояния, сообщение об ошибке и задержку запроса.

Как снизить количество ошибок API

Лучший способ снизить количество ошибок API — это не просто добавить повторные попытки.

Надёжное AI-приложение должно использовать правильный эндпоинт и модель, валидировать параметры запроса, реализовывать разумную логику повторов и задержки, поддерживать подходящие настройки таймаута и избегать отправки специфичных для провайдера параметров на несовместимый upstream.

Приложения, использующие инструменты, reasoning, thinking или многошаговые запросы Responses API, также должны корректно сохранять соответствующее состояние разговора.

Для мультипровайдерных систем особенно важно преобразование запросов с учётом конкретной модели. Claude, Codex, GLM и Kimi могут предоставлять похожие API, но это не значит, что их схемы запросов и поведенческие требования идентичны.

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

Почему AI API-шлюз может упростить обработку ошибок

Построение прямых интеграций с несколькими AI-провайдерами может очень быстро стать сложным.

Команде разработки может потребоваться по отдельности управлять Claude API, OpenAI/Codex API, GLM API, Kimi API, учётными данными аутентификации, именами моделей, специфичными для провайдера параметрами, ограничениями частоты, повторами, доступностью аккаунтов и статусом сервиса.

API-шлюз может централизовать часть этой инфраструктуры.

Вместо поддержки нескольких независимых интеграций разработчики могут использовать единый API-интерфейс и выбирать нужную модель или группу.

Это особенно полезно для AI-приложений кодирования, где разработчики могут хотеть Claude для reasoning, Codex для программной инженерии, Kimi для задач с большим контекстом и GLM для чувствительных к стоимости рабочих нагрузок.

Использование DDShub, когда вы не хотите разбираться со всем самостоятельно

Для разработчиков, использующих AI API через шлюз, ошибка не всегда является чем-то, что можно решить на стороне клиента.

Иногда реальная проблема находится на upstream. Иногда нужно переключить канал. Иногда аккаунт нужно исключить из ротации. Иногда запросу требуется преобразование протокола. Иногда провайдер изменил поведение своего API.

Именно здесь DDShub может быть полезен.

DDShub предоставляет API-доступ к нескольким AI-моделям, включая Claude, Codex, GLM и Kimi, через единую платформу. Вместо того чтобы по отдельности управлять несколькими upstream-провайдерами и устранять проблемы каждой специфичной для провайдера интеграции, разработчики могут использовать DDShub как слой доступа к API.

Что ещё важнее, DDShub предоставляет поддержку клиентов по устранению проблем с API. Когда ошибку невозможно решить простым изменением конфигурации клиента, пользователи могут предоставить команде поддержки сообщение об ошибке, модель, эндпоинт и информацию о запросе, чтобы проблему можно было исследовать со стороны шлюза и upstream.

Это особенно полезно для разработчиков, использующих Claude Code, Codex, Cursor, VS Code, OpenClaw или другие AI-инструменты кодирования, где сбой API может прервать активный рабочий процесс разработки.

Вы можете изучить доступные модели и текущие варианты API на сайте DDShub: DDShub AI Models

Для информации об интеграции API: DDShub API Documentation

Заключительные мысли

Ошибки API — нормальная часть работы с современной AI-инфраструктурой, но их становится намного проще решать, как только разработчики понимают цепочку запросов.

400 обычно означает, что нужно изучить запрос. 401 указывает на аутентификацию, тогда как 403 обычно свидетельствует о проблеме с правами. 404 обычно означает, что эндпоинт или ресурс не найден, а 429 требует исследования ограничений частоты, квоты, параллелизма или ёмкости модели.

Самая важная ошибка, которую следует тщательно исследовать, — часто именно 502.

502 Bad Gateway не обязательно означает, что шлюз неисправен. Как показывают реальные issue Sub2API, upstream-ошибка 400, 404, неподдерживаемый параметр, недействительное состояние разговора или проблема маршрутизации аккаунта могут в конечном итоге представиться клиенту как 502.

Поэтому для разработчиков, работающих с Claude, Codex, GLM или Kimi, самая полезная привычка при устранении проблем — смотреть за пределы кода состояния и определять, где именно в цепочке запросов на самом деле произошёл сбой.

Если вы не хотите тратить часы на самостоятельное исследование специфичных для провайдера ошибок, различий протоколов, upstream-аккаунтов и логов шлюза, API-платформа, такая как DDShub, может предоставить дополнительный слой поддержки с несколькими моделями, доступными через единую API-среду, и клиентским сервисом, доступным, когда проблема требует исследования за пределами конфигурации клиента.

В AI-разработке надёжный API — это не только то, успешен ли запрос. Это также о том, насколько быстро вы можете понять и решить проблему с запросом, когда он завершается сбоем.