↓
Rivya AI Docs

API errors, rate limits, and retries

Handle Rivya API error codes, HTTP status codes, rate limits, and idempotency conflicts. Check what happened before retrying a generation or chat request.

Last reviewed on November 5, 2026

Rivya API errors include an error.code and a readable error.message. Use the code and HTTP status to decide what to do next; keep the message and requestId for troubleshooting.

A failed request does not always mean a generation failed. If you already have a task ID, check its status before submitting another generation.

Error shape

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

For streaming chat, an error after the stream starts arrives as an SSE error event. The HTTP connection may already have a 200 status, so also check the stream events. See Chat API for the event format.

Include requestId when contacting Rivya support about an API request. Do not include your API key.

Stable error codes

CodeHTTP statusMeaningSuggested action
public_api_disabled503Public API access is currently disabled.Wait before trying again. Studio availability is separate.
api_key_missing401No Bearer API key was provided.Send Authorization: Bearer rvya_sk_....
api_key_invalid401The supplied key cannot be verified.Check that you copied the full key. Replace it if it is no longer usable.
api_key_revoked401The key is inactive, or its account cannot use it.Check the key in Settings. Contact support if access to the account is restricted.
api_key_expired401The key has expired.Create a new key.
api_scope_denied403The key lacks the required scope.Use a key with the scope required by this endpoint.
rate_limited429The request was rate-limited, or upload capacity is temporarily full.Reduce request frequency and retry with backoff.
validation_failed400The request body or model-specific input is invalid.Check the endpoint schema and the model's input requirements.
not_found404The model or resource was not found or is unavailable to this account.Check the model or resource ID. For owned tasks, files, and sessions, use the account that created them.
webhook_url_rejected400The webhook URL is not allowed.Use a public HTTPS URL without credentials, fragments, or private network addresses.
chat_model_not_supported400The selected model is unavailable for Rivya Chat API.Choose an available chat model from /api/v1/models.
chat_session_conflict409The session cannot be used for this chat request.Check the session, selected model, and request against the Chat API guide.
chat_attachment_not_supported400The attachment is unavailable or unsupported for this chat request.Use an available image file_id owned by the account, and check the model's image limits and supported formats.
idempotency_conflict409The key was reused with different input, or the original request has no stored response yet.Check the original request. For unchanged input that is still pending, wait before retrying with the same key.
insufficient_credits402The account has insufficient credits for the request.Check the balance and the request's credit cost before adding credits or changing the request.
internal_error500Rivya could not complete the request.Check any existing task or session first. Retry cautiously with the same idempotency key, or contact support with requestId.

Rate limits

Generation creation, file uploads, non-streaming chat, and streaming chat have separate rate-limit counters for each API key. They use one-minute windows; the current limits are configured by Rivya.

File uploads also share a concurrent-upload limit. An upload can return rate_limited while that shared capacity is full, even if the API key has not reached its own rate limit.

Generation creation uses PUBLIC_API_RATE_LIMIT_PER_MINUTE. File uploads use PUBLIC_API_FILE_RATE_LIMIT_PER_MINUTE. Both chat modes use PUBLIC_API_CHAT_RATE_LIMIT_PER_MINUTE, with separate counters for each mode. These are deployment settings, not request parameters.

After rate_limited, increase the delay between attempts and add jitter so clients do not all retry at once. Limit the number of retries. Rivya's current error response does not guarantee a Retry-After header.

Idempotent retries

Send Idempotency-Key when submitting POST /api/v1/generations, POST /api/v1/chat/completions, or POST /api/v1/chat/completions/stream. Keep the key at 128 characters or fewer.

  • Choose a unique key for each generation or chat turn.

  • Reuse that key only when retrying the same operation with the same body and API key.

  • Save the generation's public task ID or the chat response's session_id.

  • Use a new key when you intentionally change the model, prompt, message, attachments, or params.

If the connection drops before you receive a response, the outcome is uncertain. Retrying the unchanged request with the same key can return its stored response. Do not switch to a new key just because the first response was lost.

A stored response may be a success or an error. Repeating the same key can replay that error rather than execute the request again. If the original request has not stored a response yet, an unchanged retry can return idempotency_conflict; wait and check the original operation instead of treating the conflict as proof that it failed.

Streaming retries do not replay the original token deltas. A completed chat replay returns a short SSE sequence containing the saved result. See Chat API for the stream events and session read endpoint.

Retry decisions

For rate_limited, wait and retry with backoff. For public_api_disabled, wait until API access is available again. For a network interruption or internal_error, check any known task or session and follow the idempotency rules above. None of these responses guarantees that another attempt will succeed.

Fix the key, permissions, input, URL, model, session, attachment, or balance before retrying the corresponding authentication, scope, validation, webhook, chat, or credit error. Repeating an unchanged invalid request will not resolve it.

For idempotency_conflict, distinguish a changed body from a request whose response is still pending. Change the key only for an intentionally new operation; do not create a duplicate while the original outcome is unknown.

Common questions

Does a failed status query mean the generation failed?

No. A query error means you did not obtain a new task status. Keep the last status you received and retry the status query when appropriate. Treat the task as failed only when its returned status is failed.

Can I retry after the Chat API stream closes unexpectedly?

First check any known API-created session for the completed assistant message. A disconnected stream can leave the outcome uncertain. If you retry the same turn, keep its original body and idempotency key; a saved completion is replayed as a short result sequence rather than historical deltas.

Will retrying with the same key always start the request again?

No. It may return a stored success, a stored error, or a conflict while the original response is pending. Check the original operation before deciding to submit a new request.