Обрабатывайте публичные коды ошибок Rivya API, HTTP-статусы, лимиты частоты, конфликты идемпотентности и решения о повторах.

Rivya API возвращает стабильные публичные коды ошибок в JSON. Считайте значение error.code контрактом интеграции.

Форма ошибки

{
  "error": {
    "code": "api_key_missing",
    "message": "A valid Bearer API key is required.",
    "requestId": "req_..."
  }
}

Сохраняйте requestId в своих логах, когда просите поддержку Rivya расследовать неудачный API-запрос.

Стабильные коды ошибок

Код	HTTP-статус	Значение	Рекомендуемое действие
`public_api_disabled`	503	Вызовы Public API временно отключены.	Повторите позже или используйте Studio вручную.
`api_key_missing`	401	Запрос не включал API-ключ Bearer.	Отправьте `Authorization: Bearer rvya_sk_...`.
`api_key_invalid`	401	Ключ нельзя проверить.	Проверьте ключ и при необходимости выполните ротацию.
`api_key_revoked`	401	Ключ был отозван в настройках.	Создайте новый ключ.
`api_key_expired`	401	Ключ больше не действителен.	Создайте новый ключ.
`api_scope_denied`	403	У ключа нет требуемой области доступа.	Создайте ключ с нужной областью доступа.
`rate_limited`	429	Слишком много запросов в текущем окне.	Отступите и повторите позже.
`validation_failed`	400	Тело запроса, модель, промпт или параметры недействительны.	Сравните тело запроса со справочником модели.
`not_found`	404	Запрошенная задача не существует или не принадлежит аккаунту.	Проверьте публичный ID задачи и границу аккаунта.
`webhook_url_rejected`	400	URL конечной точки вебхука не разрешен.	Используйте публичный HTTPS URL без учетных данных, фрагментов, localhost или адресов частной сети.
`chat_model_not_supported`	400	Выбранная модель недоступна для Chat API.	Прочитайте `/api/v1/models` и выберите доступную чат-модель.
`chat_session_conflict`	409	Сессию Chat нельзя использовать для этого запроса.	Используйте сессию, созданную через API и принадлежащую тому же аккаунту и модели.
`chat_attachment_not_supported`	400	Вложение Chat не поддерживается.	Загрузите изображение через Files API и передайте его `file_id`.
`idempotency_conflict`	409	Тот же ключ идемпотентности был повторно использован с другим вводом.	Используйте новый ключ или отправьте точно то же тело запроса.
`insufficient_credits`	402	На аккаунте недостаточно кредитов.	Добавьте кредиты или выберите запрос с меньшей стоимостью.
`internal_error`	500	Запрос не удалось завершить.	Повторите с идемпотентностью или обратитесь в поддержку с `requestId`.

Лимиты частоты

Rivya применяет лимиты частоты Public API на уровне приложения для каждого API-ключа. Стандартный боевой лимит настроен через PUBLIC_API_RATE_LIMIT_PER_MINUTE.

Когда вы получаете rate_limited, используйте экспоненциальную задержку между повторами. Не повторяйте запросы в плотном цикле.

Идемпотентные повторы

Отправляйте Idempotency-Key с каждым боевым запросом POST /api/v1/generations и POST /api/v1/chat/completions.

Рекомендуемый шаблон:

генерируйте уникальный ключ для каждого логического запроса генерации
повторно используйте тот же ключ только при повторе того же тела запроса
сохраняйте возвращенный публичный ID задачи в собственной записи задачи
для Chat API сохраняйте возвращенный session_id, когда хотите продолжить тот же разговор
не используйте один ключ для другой модели, промпта или параметров

Если после отправки произошел сетевой сбой, повторите запрос с тем же телом запроса и тем же Idempotency-Key. Rivya может вернуть сохраненный публичный ответ вместо создания дублирующей задачи.

Решения о повторах

Повторяйте эти ошибки с задержкой между попытками:

public_api_disabled
rate_limited
internal_error
временные сетевые сбои

Не повторяйте эти ошибки без изменения ввода:

api_key_invalid
api_key_revoked
api_scope_denied
validation_failed
webhook_url_rejected
chat_model_not_supported
chat_session_conflict
chat_attachment_not_supported
idempotency_conflict
insufficient_credits

Ошибки и лимиты API

Форма ошибки

Стабильные коды ошибок

Лимиты частоты

Идемпотентные повторы

Решения о повторах

Связанные страницы

Содержание