Устранение неполадок

Начните с симптома, затем выполните исправление. Большинство сбоев связаны с base URL, key, ID модели или балансом.

Таблица по симптомам

Аутентификация

Отозванный key возвращает сообщение с префиксом key:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "API Key has been revoked (keyPrefix=...)"
}

Чек-лист:

• Заголовок — Authorization: Bearer <key> для Model API и Felo APIs.
• Data API также принимает X-API-Key: <key>.
• Key не обёрнут в кавычки и не содержит завершающего перевода строки из скопированной переменной окружения.
• В окружении развёртывания переменная действительно задана; key, работающий локально, может отсутствовать в production.
• Key не удалён и не ротирован. Удалённый или ротированный key нельзя показать снова; создайте новый.

Создание key и ограничения см. в разделе Аутентификация.

Ловушки base URL

Две частые ошибки:

1. Добавление /chat/completions к base URL, который SDK уже расширяет.
2. Установка Anthropic base URL в https://openapi.felo.ai/api/v1. SDK добавляет /v1/messages, и запрос превращается в /api/v1/v1/messages.

Проблемы с ID модели

ID моделей — это публичные ID из каталога, а не внутренние имена upstream-провайдера и не отображаемые имена.

• Смотрите ID на странице моделей или в GET /api/v1/models.
• Убедитесь, что модель поддерживает протокол, который вы вызываете (supported_protocols).
• Если вы закрепили канал, убедитесь, что он опубликован и исполняем для этой модели. Недоступный канал — не fallback.

См. Каналы и маршрутизация провайдеров.

Проблемы со streaming

• Устанавливайте stream: true в теле запроса, а не как query-параметр.
• Читайте тело ответа как поток. Ожидание полного ответа лишает streaming смысла.
• Некоторые прокси и serverless-платформы буферизуют ответы. Отключите буферизацию для маршрута, который проксирует запрос.
• Chat Completions стримит choices[0].delta, а не choices[0].message. Итоговый контент приходит множеством chunks.
• При обрыве соединения поток может закончиться без чистого терминального события. Считайте оборванное соединение незавершённым ответом.

Проблемы с асинхронными задачами

• Опрашивайте endpoint статуса, принадлежащий группе задачи. Рабочие процессы Felo используют GET /v2/tasks/{task_id}/status; задачи видео и изображений моделей — собственные endpoint'ы генерации.
• Останавливайтесь на каждом терминальном статусе, включая ошибки и истечения, а не только на успехе.
• Callback'и видео и изображений сейчас игнорируются. Не ждите webhook.
• URL результата может быть недолговечным. Если скачивание истекло, запросите новый URL у endpoint'а статуса.
• Проверьте задачу перед повторной отправкой. Повторная отправка работающей задачи создаёт дубликат, и обе будут оплачены.

См. Асинхронные задачи.

Проблемы с Data API

• Сохраняйте точный путь метода из справочника Data API.
• Тела запросов зависят от поставщика. Поле, работающее у одного поставщика, не гарантировано у другого.
• Ошибка провайдера может прийти внутри ответа 4xx с сообщением конкретного провайдера. Логируйте request_id и тело ответа.

Напоминания о безопасности

• Никогда не помещайте API key в код браузера, бандл мобильного приложения или публичный репозиторий. Держите его на сервере и проксируйте запросы.
• Не логируйте полный key. Если нужно идентифицировать, логируйте префикс.
• Немедленно ротируйте key, если он мог утечь.

Перед обращением в поддержку

Соберите:

1. Endpoint и HTTP method.
2. HTTP-статус, code и request_id.
3. ID модели или ID задачи.
4. Время с часовым поясом.
5. Минимальное тело запроса без секретов.

Отправьте это в поддержку вместе с email аккаунта. Не включайте полный API key.

Связанные разделы

• Ошибки, лимиты и повторные попытки
• Протоколы и SDK
• Оплата и кредиты
• Аутентификация