Коды ошибок и повторные попытки
При возникновении ошибки интерфейс возвращает статус-код, отличный от 2xx, а тело ответа — JSON:
{ "error": { "message": "Описание ошибки", "type": "invalid_request_error", "code": "..." }}Распространённые коды ошибок
| HTTP статус | Частая причина | Рекомендуемое действие |
|---|---|---|
| 400 | Ошибка параметров, неверный формат тела запроса | Проверьте параметры и формат JSON |
| 401 | Ключ отсутствует / недействителен | Проверьте Authorization: Bearer sk-... |
| 403 | Токен отключён, нет доступа к группе моделей | Проверьте в консоли статус токена и группу |
| 404 | Имя модели не существует или недоступно | См. Обзор моделей |
| 413 | Тело запроса слишком большое (превышен контекст) | Уменьшите messages или выберите модель с большим контекстом |
| 429 | Ограничение по частоте или недостаточно лимита | Повторяйте с задержкой, см. Ограничения и 429 |
| 500 / 502 / 503 | Нестабильность upstream-модели | Повторите после короткой паузы, шлюз автоматически переключится на доступный upstream |
Рекомендации по повторным попыткам
- Для 429 / 5xx используйте экспоненциальную задержку + джиттер: например, 1s, 2s, 4s, максимум 3–5 попыток;
- 400 / 401 / 403 — это детерминированные ошибки, повторные попытки не имеют смысла, сначала исправьте запрос;
- В сценариях с идемпотентностью (например, генерация изображений) перед повторной отправкой сначала убедитесь в окончательном статусе предыдущего запроса, чтобы избежать двойного списания;
- В production-среде рекомендуется записывать заголовки ответа и
error.message, чтобы было проще определить, на каком этапе возникла ошибка.