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
| Code | HTTP status | Meaning | Suggested action |
|---|---|---|---|
public_api_disabled | 503 | Public API access is currently disabled. | Wait before trying again. Studio availability is separate. |
api_key_missing | 401 | No Bearer API key was provided. | Send Authorization: Bearer rvya_sk_.... |
api_key_invalid | 401 | The supplied key cannot be verified. | Check that you copied the full key. Replace it if it is no longer usable. |
api_key_revoked | 401 | The 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_expired | 401 | The key has expired. | Create a new key. |
api_scope_denied | 403 | The key lacks the required scope. | Use a key with the scope required by this endpoint. |
rate_limited | 429 | The request was rate-limited, or upload capacity is temporarily full. | Reduce request frequency and retry with backoff. |
validation_failed | 400 | The request body or model-specific input is invalid. | Check the endpoint schema and the model's input requirements. |
not_found | 404 | The 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_rejected | 400 | The webhook URL is not allowed. | Use a public HTTPS URL without credentials, fragments, or private network addresses. |
chat_model_not_supported | 400 | The selected model is unavailable for Rivya Chat API. | Choose an available chat model from /api/v1/models. |
chat_session_conflict | 409 | The session cannot be used for this chat request. | Check the session, selected model, and request against the Chat API guide. |
chat_attachment_not_supported | 400 | The 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_conflict | 409 | The 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_credits | 402 | The account has insufficient credits for the request. | Check the balance and the request's credit cost before adding credits or changing the request. |
internal_error | 500 | Rivya 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.
