Обработка ошибок API
Прочитайте публичную ошибку, выберите безопасное действие и подготовьте данные для поддержки.
Обновлено
При ошибке сначала сохраните HTTP-статус и ответ API, затем прочитайте публичный код. Не заменяйте точный ответ предположением по одному статусу: одинаковый статус может требовать разных действий.
Прочитайте совместимую с OpenAI ошибку
Обычная ошибка Chat Completions имеет объект error. Например, временная недоступность модели возвращается в такой публичной форме:
{
"error": {
"code": "MODEL_NOT_AVAILABLE",
"message": "The selected model is temporarily unavailable. Please try again.",
"param": null,
"type": "server_error"
}
}Используйте error.code для логики клиента, error.message для понятной диагностики, error.param для связанного поля и error.type для класса ошибки. Не разбирайте текст сообщения, если уже есть публичный код.
Некоторые ошибки проверки модели дополнительно возвращают стабильные поля code и model на верхнем уровне. Ошибки оплаты также могут использовать верхнеуровневые поля: например, недостаток средств сообщает текущую и требуемую сумму, а лимит ключа — API_KEY_SPEND_LIMIT_EXCEEDED, период, суммы и resetAt. Сохраняйте фактическое тело ответа и не предполагайте, что каждая ошибка вложена одинаково.
Решение зависит от HTTP-статуса и публичного кода, а не от внутренних причин.
Выберите действие по статусу и коду
| Сигнал | Что проверить | Действие |
|---|---|---|
HTTP 400 | error.code, error.param, model и тело запроса | Исправьте формат, контекст, предел ответа или неподдерживаемую возможность. Не повторяйте то же тело. |
HTTP 401 | Заголовок Bearer и состояние ключа | Подставьте действующий ключ активного рабочего пространства. Потерянный или раскрытый ключ отзовите и замените. |
HTTP 402 | Доступный баланс и активные резервы | Дайте активным резервам завершиться или освободиться и снова проверьте доступный баланс, прежде чем пополнять пространство или уменьшать запрос. |
HTTP 403 | Публичный код и роль в рабочем пространстве | Исправьте права доступа. Только при FIRST_TOP_UP_REQUIRED используйте возвращённый topUpUrl для первого реального пополнения. |
HTTP 429 | Верхнеуровневый code и resetAt, если он есть | Для API_KEY_SPEND_LIMIT_EXCEEDED дождитесь resetAt или измените лимит; временный лимит повторяйте только по правилам лимитов и повторов. |
HTTP 5xx | Публичный код, был ли уже получен результат | Следуйте правилам ограниченных повторов. После любого результата не запускайте автоматический дубликат. |
| Нет HTTP-ответа | Сеть клиента, DNS, TLS, отмена и факт получения частей ответа | Отсутствие результата не подтверждает, что запрос не был принят. Проверьте Использование, точное время и модель, затем примите явное решение по правилам повторов. |
FIRST_TOP_UP_REQUIRED и topUpUrl являются опубликованной формой блокировки модели в подходящем личном пространстве. Не считайте любую ошибку 403 требованием пополнить баланс: она также может означать недостаточные права.
Различайте ошибки изображений
Проверка параметров изображений использует MODEL_PARAMETER_COMBINATION_INVALID, когда модель не принимает сочетание опций, и MODEL_CAPABILITY_METADATA_UNAVAILABLE, когда метаданные возможностей временно нельзя проверить.
Ошибки выполнения изображений используют текущие публичные коды IMAGE_UPSTREAM_INVALID_REQUEST, IMAGE_UPSTREAM_INVALID_RESPONSE, IMAGE_UPSTREAM_RATE_LIMITED, IMAGE_UPSTREAM_UNAVAILABLE, IMAGE_UPSTREAM_FAILED, IMAGE_ARTIFACT_STORAGE_FAILED и IMAGE_REQUEST_ABORTED. Клиент должен показать безопасное сообщение и выбрать действие по коду, не раскрывая название внешнего сервиса или его ответ.
Подготовьте безопасные данные для поддержки
Перед обращением в поддержку соберите:
- точный HTTP-статус, публичный код и безопасное сообщение;
- адрес API и точный идентификатор модели;
- идентификатор запроса, если его показывает клиент или раздел использования;
- точное время с часовым поясом и название и версию клиента или инструмента;
- название ключа и видимый маскированный префикс;
- очищенное тело запроса, только если без него нельзя воспроизвести ошибку.
Не отправляйте секреты и внутренние детали
Не прикладывайте полный API-ключ, пароль, платёжные данные, конфиденциальный запрос, названия внешних сервисов, внутренние маршруты или полные ответы внешней системы. Для диагностики достаточно публичной ошибки и безопасных идентификаторов.