Обробляйте публічні коди помилок 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	Запит не містить Bearer API key.	Надішліть `Authorization: Bearer rvya_sk_...`.
`api_key_invalid`	401	Ключ неможливо перевірити.	Перевірте ключ і за потреби виконайте ротацію.
`api_key_revoked`	401	Ключ було відкликано в налаштуваннях.	Створіть новий ключ.
`api_key_expired`	401	Ключ більше не чинний.	Створіть новий ключ.
`api_scope_denied`	403	Ключ не має потрібного scope.	Створіть ключ із потрібним scope.
`rate_limited`	429	Забагато запитів у поточному вікні.	Зменште частоту й повторіть пізніше.
`validation_failed`	400	Тіло запиту, model, prompt або params невалідні.	Зіставте тіло запиту з довідником моделі.
`not_found`	404	Запитана задача не існує або не належить акаунту.	Перевірте публічний ID задачі й межу акаунта.
`webhook_url_rejected`	400	URL endpoint webhook не дозволено.	Використовуйте публічний HTTPS URL без credentials, fragments, localhost або приватних мережевих адрес.
`chat_model_not_supported`	400	Вибрана модель недоступна для Chat API.	Прочитайте `/api/v1/models` і виберіть доступну модель чату.
`chat_session_conflict`	409	Сесію чату не можна використати для цього запиту.	Використайте сесію, створену через API, яка належить тому самому акаунту й моделі.
`chat_attachment_not_supported`	400	Вкладення чату не підтримується.	Завантажте зображення через Files API і передайте його `file_id`.
`idempotency_conflict`	409	Той самий ключ ідемпотентності повторно використано з іншими вхідними даними.	Використайте новий ключ або повторно надішліть точно те саме тіло запиту.
`insufficient_credits`	402	В акаунті недостатньо кредитів.	Додайте кредити або виберіть дешевший запит.
`internal_error`	500	Запит не вдалося завершити.	Повторіть із ключем ідемпотентності або зверніться в підтримку з `requestId`.

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

Rivya застосовує ліміти частоти Public API на рівні застосунку для кожного API-ключа. Стандартний production-ліміт налаштовується через PUBLIC_API_RATE_LIMIT_PER_MINUTE.

Коли отримуєте rate_limited, використовуйте експоненційне відтермінування. Не повторюйте запит у щільному циклі.

Ідемпотентні повтори

Надсилайте Idempotency-Key з кожним production-запитом POST /api/v1/generations і POST /api/v1/chat/completions.

Рекомендований патерн:

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

Якщо мережа падає після надсилання, повторіть із тим самим тілом запиту і тим самим 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

Форма помилки

Стабільні коди помилок

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

Ідемпотентні повтори

Рішення щодо повторної спроби

Пов'язані сторінки

Зміст