Ошибки

Формат обёртки ошибки

{
  "error": {
    "message": "Human-readable description of what went wrong",
    "type": "invalid_request_error"
  }
}

Это та же обёртка, что использует собственный API OpenAI, поэтому обработка ошибок, написанная для существующего OpenAI-совместимого клиента, должна продолжать работать без изменений: сначала проверяйте код статуса HTTP, а error.message читайте как сообщение, которое стоит показать разработчику или залогировать. error.type — стабильная, машинно-проверяемая категория, полезная для ветвления логики (повторять запрос или нет, запрашивать новый API-ключ или подождать и попробовать снова), без разбора текста сообщения.

Коды статуса и типы

Статус	Тип	Значение
400	invalid_request_error	Сам запрос сформирован неверно: нераспознанная model, отсутствующий или пустой массив messages, сообщение с неподдерживаемой ролью или некорректно оформленное определение tools. Исправьте запрос; повтор без изменений будет каждый раз завершаться той же ошибкой.
401	authentication_error	Заголовок Authorization отсутствует, сформирован неверно, либо ключ недействителен, истёк или отозван. См. Аутентификация.
429	rate_limit_error	Слишком много запросов за короткий промежуток времени с этим ключом. О лимите и о том, как корректно снизить частоту, см. в разделе Лимиты запросов.
500	api_error	Непредвиденная ошибка на стороне сервера, не связанная с вашим запросом. Встречается редко; можно безопасно повторить, желательно с небольшой задержкой.
503	api_error	Сервис временно не может обработать запрос, как правило, из-за временной проблемы на собственной инфраструктуре генерации tAI, а не из-за чего-то неверного в вашем запросе. Можно безопасно повторить.

Несколько примеров

Неизвестная модель:

HTTP/1.1 400 Bad Request

{"error": {"message": "Unknown model: 'tai-4.9'. See https://docs.artfical.com/tai/en for the current list.", "type": "invalid_request_error"}}

Недействительный или истёкший ключ:

HTTP/1.1 401 Unauthorized

{"error": {"message": "Invalid API key.", "type": "authentication_error"}}

Временная проблема с сервисом:

HTTP/1.1 503 Service Unavailable

{"error": {"message": "The AI service is temporarily unavailable. Please retry.", "type": "api_error"}}

Ошибки посреди потока

Как только потоковый ответ начался (соединение открыто и чанки уже начали приходить), об ошибке больше нельзя сообщить в виде обычного тела JSON с не-2xx статусом, поскольку HTTP-статус и заголовки уже были отправлены как 200 в начале потока. Вместо этого сбой, произошедший посреди потока, отображается как видимый чанк содержимого (как правило, короткое уведомление в квадратных скобках), за которым следует обычный финальный чанк и [DONE], а не просто обрыв соединения. Точный формат и то, почему поток в любом случае гарантированно корректно завершается, см. в разделе Потоковая передача.

Что имеет смысл повторять

Общее правило: ошибки 400 и 401 описывают проблему с самим запросом или ключом, и идентичный повтор будет каждый раз завершаться так же, поэтому сначала нужно исправить первопричину. 429, 500 и 503 можно безопасно повторять, желательно с небольшой задержкой и ограничением на общее число попыток, а не в плотном цикле; о том, как правильно снижать частоту после 429, см. отдельно в разделе Лимиты запросов.