Ошибки
Коды ошибок API Флоктора: формат ответа, заголовок X-Floctor-Error-Code, что означают 401, 402, 404 и 429 и какие запросы стоит повторять.
Ошибка приходит в формате того протокола, на котором вы работаете, чтобы ваш SDK разобрал её как свою.
Anthropic:
{
"type": "error",
"error": { "type": "authentication_error", "message": "..." }
}OpenAI:
{
"error": { "message": "...", "type": "invalid_request_error", "code": null, "param": null }
}Заголовок с точным кодом
Типы ошибок в обоих протоколах слишком общие: под invalid_request_error помещается и нехватка денег, и неизвестная модель. Поэтому к каждому отказу мы добавляем свой заголовок:
X-Floctor-Error-Code: spend_limit_exceededИменно на него имеет смысл смотреть в коде: он не зависит от того, каким протоколом вы пользуетесь.
К некоторым отказам добавляется Retry-After с числом секунд. Он приходит там, где момент окончания известен точно: например, у предела трат, где известен конец периода. На остальных отказах этого заголовка нет.
Таблица кодов
| Код | HTTP | Что случилось |
|---|---|---|
model_not_found | 404 | Такой модели нет. Скорее всего, она переименовалась, см. «Модели». |
invalid_request | 422 | Тело запроса не соответствует протоколу. |
insufficient_balance | 402 | На балансе аккаунта не хватает средств на этот запрос. |
spend_limit_exceeded | 429 | Ключ упёрся в свой предел трат. Приходит с Retry-After. |
concurrency_exceeded | 429 | Слишком много одновременных запросов. Повторите позже. |
idempotency_conflict | 409 | Тот же Idempotency-Key уже использован для другого тела. |
idempotency_request_in_progress | 409 | Запрос с этим ключом ещё выполняется. |
idempotency_result_already_completed | 409 | Запрос с этим ключом уже завершился. Повторно не выполнялся и не оплачивался. |
idempotency_result_failed | 409 | Запрос с этим ключом уже завершился неудачей. Повторно не выполнялся. |
idempotency_result_cancelled | 409 | Запрос с этим ключом был отменён. Повторно не выполнялся. |
idempotency_result_indeterminate | 409 | Исход первого запроса неизвестен, автоматически повторить его нельзя. |
upstream_rejected | как у модели | Модель отклонила запрос сама, её код ответа передан без изменений. |
upstream_unavailable | 502 | До модели не удалось достучаться. |
upstream_indeterminate | 502 | Неизвестно, выполнился ли запрос. Мы его не повторяли, резерв средств снят. |
server_shutting_down | 503 | Сервер перезапускается и не начинал ваш запрос. Приходит с Retry-After. |
internal_error | 500 | Ошибка на нашей стороне. |
Отдельно стоит 401 без нашего кода: ключ не принят. Он либо скопирован не целиком, либо отозван.
Какие запросы стоит повторять
Повторить с паузой имеет смысл:
429обоих видов — состояние временное,Retry-Afterподскажет, когда;503— запрос не начинался;502сupstream_unavailable— до модели не дошли, значит, ничего не выполнилось.
Повторять бесполезно:
400,404,422— запрос сам по себе не изменится, менять надо его;402— нужно пополнить баланс;409— первый запрос с этим ключом уже что-то решил, посмотрите код, чтобы понять что.
Отдельный случай — 502 с кодом upstream_indeterminate. Он означает, что судьба запроса неизвестна: дошёл он до модели или нет, установить не удалось. Автоматически мы такой запрос не повторяем, потому что повтор может выполнить работу и списать деньги второй раз. Безопасно повторить его можно с заголовком Idempotency-Key.
Списываются ли деньги при ошибке
Нет. Неудачная попытка не стоит ничего: списывается только то, что модель действительно отработала. Отказ на любом шаге до этого — и на нашей стороне, и на стороне модели — денег не стоит.