Руководства

Ошибки, лимиты и повторные попытки

Читайте ответы с ошибками и заголовки лимитов, повторяйте запросы безопасно и диагностируйте типичные сбои.

Каждый Felo API возвращает JSON-тело ошибки со стабильным кодом и request ID. Сначала читайте HTTP-статус, затем code, затем message.

Оболочка ошибки

Текущие production-ответы используют HTTP-статус как status:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid API Key",
  "request_id": "202610221444486982113280416060637185"
}

Поле	Значение
`status`	HTTP-статус, повторённый в теле
`code`	Машиночитаемый код ошибки
`message`	Понятное человеку объяснение
`request_id`	Непрозрачный идентификатор запроса; указывайте его в обращениях в поддержку

В некоторых старых примерах endpoint'ов используется status: "error" и другая строка кода. Ориентируйтесь на HTTP-статус и code, а не на точную формулировку message.

Частые коды

HTTP	Code	Что означает	Что делать
400	Код валидации endpoint'а	Параметр отсутствует или неверен	Исправьте запрос; не повторяйте его без изменений
401	`UNAUTHORIZED`	API key отсутствует, неверен, истёк или отозван	Отправьте `Authorization: Bearer $FELO_API_KEY`; при отзыве ротируйте key
402	`INSUFFICIENT_CREDITS`	Недостаточно сервисных кредитов	Пополните баланс в Console Billing и повторите
404	Зависит от endpoint'а	Неизвестная модель, задача или маршрут	Проверьте ID модели или задачи и путь endpoint'а
429	`RATE_LIMITED`	Превышен лимит запросов	Дождитесь `Retry-After` и повторите
5xx	`CHAT_FAILED`, `*_FAILED`, `SERVICE_UNAVAILABLE`	Сбой upstream или сервиса	Повторите с backoff; если не проходит, обратитесь в поддержку

Справочники endpoint'ов перечисляют коды, специфичные для них. Начните с ошибок Chat API или справочника нужного endpoint'а.

Request ID

Тела ошибок Felo содержат request_id. Записывайте его вместе с endpoint'ом, HTTP-статусом, кодом ошибки, ID модели и ID задачи. Никогда не логируйте полный API key.

Model API также принимает необязательный заголовок запроса X-Request-Id. Если вы его отправите, он вернётся в ответе для диагностики, что позволяет сопоставить ваши логи с запросом. Если не отправляли — используйте возвращённый request_id.

Лимиты запросов

/v2/chat — единственный Felo endpoint с документированными принудительными лимитами:

На API key, окно 1 минута.
На пользователя, окно 1 минута.
На пользователя, окно 1 час.

Пользователи с действующей платной подпиской Felo, включая корпоративные, освобождены и не получают заголовки X-RateLimit-*. Если статус подписки не удаётся проверить, лимиты применяются.

Заголовок	Значение
`X-RateLimit-Limit`	Лимит самого строгого из действующих измерений
`X-RateLimit-Remaining`	Минимальный остаток квоты по трём измерениям
`X-RateLimit-Reset`	Unix-время в секундах, когда сбрасывается текущее окно
`Retry-After`	При 429 — рекомендуемая задержка в секундах

У других endpoint'ов /v2/** сейчас нет принудительных лимитов. Запросы Model API всё равно могут ограничиваться upstream-провайдером, что проявляется как 429.

Не хардкодьте числовые лимиты. Читайте заголовки каждого ответа.

Политика повторных попыток

Ситуация	Повторять?
400, 401, 402, 404	Нет. Сначала исправьте запрос, key или баланс.
429	Да, после `Retry-After` или `X-RateLimit-Reset`.
5xx, таймауты, сбросы соединения	Да, с экспоненциальным backoff и jitter.
Соединение streaming оборвалось посреди ответа	Только если приложение допускает повторную генерацию.

Рекомендуемый цикл:

Повторяйте только идемпотентные или безопасно повторяемые запросы.
Используйте экспоненциальный backoff: начните примерно с 1 секунды, удваивайте, ограничьте 30 секундами.
Добавляйте случайный jitter, чтобы клиенты не повторяли синхронно.
Остановитесь после нескольких попыток и верните ошибку наружу.
При 429 соблюдайте Retry-After, а не собственное расписание.

Порядок диагностики

Проверьте, что key присутствует и не отозван.
Вызовите GET /api/v1/models с тем же key, чтобы подтвердить аутентификацию.
Отправьте минимальный валидный запрос к целевому endpoint'у.
Добавляйте streaming, tools или большие входные данные по одному.
Для асинхронной работы проверяйте статус задачи перед повторной отправкой.