Помилки, обмеження та повторні спроби

Кожен Felo API повертає тіло помилки JSON зі стабільним кодом помилки та ID запиту. Спершу прочитайте код стану HTTP, потім код, потім повідомлення.

Структура помилки

Поточні відповіді в продакшені використовують код стану HTTP як status:

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

Деякі старіші приклади endpoint використовують status: "error" та інший рядок коду. Орієнтуйтеся на код стану HTTP і code, а не на точне формулювання message.

Типові коди

Довідники endpoint перелічують коди, специфічні для цього endpoint. Почніть з помилок Chat API або довідника endpoint, який викликаєте.

Endpoint генерації моделей

POST /api/v1/images/generations і POST /api/v1/videos/generations повертають помилки рівня endpoint у структурі помилок OpenAI, а не в наведеній вище:

{
  "error": {
    "message": "Model kind does not match this generation endpoint",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_kind_mismatch"
  }
}

ID запиту міститься в заголовку відповіді X-Request-Id, а не в тілі. Відхилений запит не створює завдання. Коли завдання вже існує, більшість збоїв надходять як термінальний статус завдання у відповіді 200, а не як помилка HTTP: перевірте status на failed або interrupted, потім прочитайте error.message. Див. Генерація зображень і Асинхронні завдання.

ID запитів

Тіла помилок Felo містять request_id. Записуйте його в журнал разом з endpoint, кодом стану HTTP, кодом помилки, ID моделі та ID завдання. Ніколи не записуйте в журнал повний API-ключ.

Model API також приймає необов'язковий заголовок запиту X-Request-Id. Коли ви його надсилаєте, він повертається у відповіді для діагностики, що дає змогу зіставити власні журнали із запитом. Якщо ви його не надсилаєте, використовуйте повернутий request_id.

Обмеження швидкості

/v2/chat — єдиний endpoint Felo із задокументованими примусовими обмеженнями швидкості:

• Для кожного API-ключа, вікно 1 хвилина.
• Для кожного користувача, вікно 1 хвилина.
• Для кожного користувача, вікно 1 година.

Користувачі з чинною платною підпискою Felo, зокрема корпоративною, звільнені від обмежень і не отримують заголовків X-RateLimit-*. Якщо статус підписки неможливо перевірити, обмеження все одно застосовуються.

Інші endpoint /v2/** наразі не мають примусових обмежень швидкості. Запити Model API усе ще можуть обмежуватися вищим постачальником, що може проявитися як 429.

Не вшивайте числові ліміти жорстко. Читайте заголовки в кожній відповіді.

Політика повторних спроб

Рекомендований цикл:

1. Повторюйте лише ідемпотентні запити або запити, безпечні для повтору.
2. Використовуйте експоненційне збільшення інтервалу: почніть приблизно з 1 секунди, подвоюйте, обмежте 30 секундами.
3. Додавайте випадковий розкид, щоб клієнти не повторювали синхронно.
4. Зупиняйтеся після невеликої кількості спроб і повідомляйте про помилку.
5. Для 429 дотримуйтеся Retry-After замість власного графіка.

Послідовність налагодження

1. Перевірте, що ключ наявний і не відкликаний.
2. Викличте GET /api/v1/models із тим самим ключем, щоб підтвердити автентифікацію.
3. Надішліть мінімальний дійсний запит на цільовий endpoint.
4. Додавайте потокову передачу, інструменти або великі вхідні дані по одному.
5. Для асинхронної роботи перевірте статус завдання, перш ніж надсилати повторно.

Пов'язані розділи

• Автентифікація
• Канали та маршрутизація постачальників
• Асинхронні завдання
• Усунення несправностей