Коды ошибок
Что означают 401 / 403 / 404 / 429 / 5xx, диагностика в пять шагов и практики, помогающие избежать ошибок.
Когда вызов завершается ошибкой, начните с HTTP-кода состояния и сообщения об ошибке в теле ответа, а затем сопоставьте их с таблицей ниже. Большинство проблем решается первыми тремя пунктами.
Коды состояния
| Код | Значение | Частые причины и способы устранения |
|---|---|---|
| 400 Bad Request | Некорректный запрос | Повреждённый JSON или отсутствие обязательного поля (model, messages); сверьте тело запроса с документацией API |
| 401 Unauthorized | Ошибка аутентификации | Ключ неверен / удалён / истёк; см. чек-лист в разделе Аутентификация |
| 403 Forbidden | Нет доступа | У этого ключа или учётной записи может не быть доступа к запрошенной модели; проверьте в каталоге моделей, доступна ли она вам |
| 404 Not Found | Ресурс не найден | Обычно причина — опечатка в ID модели; скопируйте точный ID из каталога моделей |
| 429 Too Many Requests | Превышен лимит запросов | Слишком частые запросы. Снизьте темп (экспоненциальные интервалы) или уменьшите параллелизм; если это повторяется, обратитесь в поддержку платформы |
| 5xx | Ошибка на стороне сервера | Временный сбой платформы или вышестоящей модели. Повторите запрос один раз с теми же параметрами; если ошибка сохраняется, обратитесь в Поддержку, приложив записи запросов со страницы журналов |
Шаги диагностики
- Проверьте ключ: убедитесь на странице «API Keys», что ключ существует и не истёк; если сомневаетесь, удалите и создайте заново.
- Проверьте ID модели: скопируйте его из каталога моделей, а не вводите вручную.
- Прочитайте тело ошибки: в ответах с ошибкой обычно есть
error.messageс точной причиной (недостаточный баланс, отсутствующий параметр, ...). - Проверьте журналы: страница журналов в консоли показывает статус, задержку и расход по каждому запросу — посмотрите, ограничена ли ошибка одной моделью или одним ключом.
- Ничего не помогло: обратитесь в Поддержку, приложив метки времени и коды состояния со страницы журналов.
Практики, помогающие избежать ошибок
- Используйте официальный SDK (он берёт на себя повторы, таймауты и детали протокола);
- Реализуйте экспоненциальную задержку для 429 / 5xx вместо настойчивых повторов;
- Установите лимит расходов на продакшен-ключах, чтобы аномальный трафик не исчерпал баланс.