Handle Rivya API public error codes, HTTP status values, rate limits, idempotency conflicts, and retry decisions.

Rivya API returns stable public error codes in JSON. Treat the error.code value as the integration contract.

Error Shape

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

Keep requestId in your logs when asking Rivya support to investigate a failed API request.

Stable Error Codes

Code	HTTP status	Meaning	Suggested action
`public_api_disabled`	503	Public API calls are temporarily disabled.	Retry later or use Studio manually.
`api_key_missing`	401	The request did not include a Bearer API key.	Send `Authorization: Bearer rvya_sk_...`.
`api_key_invalid`	401	The key cannot be verified.	Check the key and rotate it if needed.
`api_key_revoked`	401	The key was revoked in Settings.	Create a new key.
`api_key_expired`	401	The key is no longer valid.	Create a new key.
`api_scope_denied`	403	The key does not have the required scope.	Create a key with the needed scope.
`rate_limited`	429	Too many requests in the current window.	Back off and retry later.
`validation_failed`	400	The body, model, prompt, or params are invalid.	Compare your body with the model reference.
`not_found`	404	The requested task does not exist or is not owned by the account.	Check the public task ID and account boundary.
`webhook_url_rejected`	400	The webhook endpoint URL is not allowed.	Use an HTTPS public URL without credentials, fragments, localhost, or private network addresses.
`chat_model_not_supported`	400	The selected model is not available for Chat API.	Read `/api/v1/models` and choose an available chat model.
`chat_session_conflict`	409	The chat session cannot be used for this request.	Use an API-created session owned by the same account and model.
`chat_attachment_not_supported`	400	The chat attachment is not supported.	Upload an image through Files API and pass its `file_id`.
`idempotency_conflict`	409	The same idempotency key was reused with different input.	Use a new key or resend the exact same body.
`insufficient_credits`	402	The account does not have enough credits.	Add credits or choose a lower-cost request.
`internal_error`	500	The request could not be completed.	Retry with idempotency or contact support with `requestId`.

Rate Limits

Rivya applies application-level Public API rate limits per API key. The default production limit is configured by PUBLIC_API_RATE_LIMIT_PER_MINUTE.

When you receive rate_limited, use exponential backoff. Do not retry in a tight loop.

Idempotent Retries

Send Idempotency-Key with every production POST /api/v1/generations and POST /api/v1/chat/completions request.

Recommended pattern:

generate a unique key per logical generation request
reuse the same key only when retrying the same body
store the returned public task ID with your own job record
for Chat API, store the returned session_id when you want to continue the same conversation
do not reuse one key for a different model, prompt, or params

If the network fails after submission, retry with the same body and the same Idempotency-Key. Rivya can return the stored public response instead of creating a duplicate task.

Retry Decisions

Retry these with backoff:

public_api_disabled
rate_limited
internal_error
temporary network failures

Do not retry these without changing input:

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 Errors and Limits

Error Shape

Stable Error Codes

Rate Limits

Idempotent Retries

Retry Decisions

Table of Contents

API Errors and Limits

Error Shape

Stable Error Codes

Rate Limits

Idempotent Retries

Retry Decisions

Related Pages

Table of Contents