неудачный запрос возвращает http-код и тело с описанием причины. причины бывают двух видов: проверки на стороне airakurs — ключ, баланс, доступ к модели — и ошибки, которые вернул конечный сервис.
тело ответа
проверки airakurs отвечают полем detail:
{
"detail": "Insufficient balance to run this request."
}ошибка конечного сервиса приводится к формату того эндпоинта, на который пришёл запрос. для эндпоинтов в формате openai это выглядит так:
{
"error": {
"message": "This model's maximum context length is 128000 tokens.",
"type": "invalid_request_error",
"param": null,
"code": null
}
}для /v1/messages — в формате anthropic ({"type": "error", "error": {…}}), для /v1beta — в формате google ({"error": {"code", "message", "status"}}). обработку ошибок в коде, написанном под конкретный формат, менять не нужно.
коды ответов
| код | причина | что делать |
|---|---|---|
| 400 | запрос не соответствует формату: неверный json, неизвестное поле, недопустимое значение | проверить тело запроса |
| 401 | ключ не распознан, не определён ip-адрес запроса или аккаунт заблокирован | проверить ключ и базовый адрес |
| 402 | недостаточно средств на балансе либо исчерпан бюджет ключа | пополнить баланс или поднять бюджет ключа |
| 403 | модель не входит в список разрешённых для ключа, ip-адрес не в белом списке, эндпоинт ключу не разрешён | проверить настройки ключа |
| 404 | модель или файл с таким идентификатором не найдены | сверить идентификатор с каталогом |
| 429 | превышен лимит частоты запросов | повторить запрос позже |
| 502 | конечный сервис недоступен или ни один из них не ответил | повторить запрос |
| 504 | истекло время ожидания ответа | повторить запрос |
точная причина всегда в тексте ошибки: например, у 402 это Insufficient balance to run this request., API Key budget exceeded. или Monthly budget exceeded. — три разные ситуации с одним кодом.
отдельный случай — 402 при непустом балансе. перед отправкой запроса его стоимость считается предварительно, с запасом на самый длинный возможный ответ, и средств должно хватать именно на эту оценку. как она устроена и как её уменьшить — в статье стоимость запроса.
ошибки от конечного сервиса
часть ошибок формирует не airakurs, а сам сервис, которому ушёл запрос: слишком длинный контекст, недопустимое значение параметра, отказ по правилам безопасности. такие ответы передаются с исходным кодом и исходным текстом, поэтому искать их описание нужно в документации соответствующего api.
что дальше
- api-ключи — ограничения ключа, из-за которых приходят 401, 402 и 403.
- лимиты — откуда берётся 429.
- стоимость запроса — предварительный расчёт, из-за которого приходит 402.
частые вопросы
как понять, кто вернул ошибку — airakurs или сама модель?
по телу ответа. проверки airakurs отвечают полем detail. ошибка конечного сервиса приходит в формате эндпоинта — например, объектом error для эндпоинтов в формате openai.
почему приходит 402, если на балансе есть деньги?
причины две. либо исчерпан бюджет ключа или месячный бюджет — это отдельные ограничения, не связанные с остатком. либо средств не хватает на предварительную оценку стоимости запроса, которая делается с запасом на самый длинный ответ. точную причину показывает текст ошибки.
что делать при ошибках 502 и 504?
повторить запрос. 504 означает, что ответ не пришёл за отведённое время, 502 — что конечный сервис недоступен. обе ошибки обычно временные.