Errors
Every error the gateway can return, with its HTTP status, error.type, error.code, cause and what to do about it.
Error envelope
OpenAI-compatible routes return errors in one JSON envelope. Branch on the HTTP status first, then on error.code, which is stable and machine-readable. error.message is written for humans and can change.
…type: the error family (invalid_request_error,permission_denied,insufficient_quota,rate_limit_exceeded,server_error, …).code: the specific reason;nullfor generic body errors.param: the offending field when known, otherwisenull.
Three responses use a different shape: 500 internal_error (adds request_id, no code), 503 maintenance_active (fields at the top level) and the 422 form validation of /v1/audio/transcriptions (detail[]). /v1/messages answers some errors in Anthropic's format, see below.
Gateway errors
Raised by RodiumAI itself, before or around the provider call. None of them is billed: when a hold was already reserved, it is released.
| HTTP | error.type | error.code | Cause | What to do |
|---|---|---|---|---|
| 400 | invalid_request_error | — | The body is not valid JSON, or is not a JSON object (every JSON endpoint). | Send Content-Type: application/json with a JSON object body. |
| 400 | invalid_request_error | missing_model | model is missing or empty. | Pass a catalogue id such as openai/gpt-4o-mini, or an alias such as rodiumai/smart. |
| 400 | invalid_request_error | invalid_model_format | model is neither <provider>/<model> nor a smart alias. | Copy the exact id from GET /v1/models (ids are case-sensitive). |
| 400 | invalid_request_error | missing_input | POST /v1/audio/speech without a non-empty input string. | Put the text to synthesise in input. |
| 400 | invalid_request_error | missing_prompt | POST /v1/videos/generations without a non-empty prompt. | Send a text prompt (also required for image-to-video). |
| 400 | invalid_request_error | invalid_value | Chat: a data: URL in an image_url (or video) content part is malformed, for example an empty MIME type. param points at the part. | Use data:image/png;base64,<payload>, an https:// URL or a gs:// URI. |
| 400 | invalid_request_error | model_not_supported_for_endpoint | The model exists but does not serve this endpoint (an embedding model on chat, a chat model on images, a TTS model on chat…). | Check rodiumai_capabilities.output_modalities in GET /v1/models and call the matching endpoint. |
| 400 | invalid_request_error | unsupported_parameter | /v1/responses was called with background: true or with conversation; neither is supported through RodiumAI. | Use stream: true for long runs, and previous_response_id (or resend the history) to continue a conversation. |
| 401 | invalid_request_error | invalid_api_key | Missing or malformed Authorization header, a key that does not start with rd_sk_, or an unknown, revoked or expired key (or a suspended owner). | Send Authorization: Bearer rd_sk_… with an active key from Dashboard → API keys. Retrying with the same key will not help. |
| 401 | invalid_request_error | invalid_token | A "Sign in with RodiumAI" access token is expired, badly signed, or issued for another issuer or client. | Refresh it with your refresh_token, or sign the user in again. |
| 401 | invalid_request_error | insufficient_scope | The OIDC access token has neither the inference nor the forge.read scope. | Request the inference scope during authorization. |
| 402 | insufficient_quota | insufficient_balance | The pre-flight hold for this request does not fit in your spendable RODI balance (or, for OIDC callers, in the FRODI allotment). | Top up in Dashboard → Billing, lower max_tokens, or use a cheaper model. Not retryable as-is. |
| 403 | permission_denied | insufficient_scope | The API key has explicit scopes and lacks the one this endpoint needs: chat:write (chat, messages, responses, images, video, audio) or embeddings:write (/v1/embeddings). | Add the scope to the key in the dashboard, or use another key. |
| 403 | permission_denied | model_not_allowed | The model is not in the key's allowed_models, or the custom model belongs to another account or organization. | Add the model to the key's allow-list, or use an unrestricted key. |
| 403 | permission_denied | api_key_quota_exceeded | The key has used up its monthly RODI quota. | Raise or remove the key's quota, or wait for the next monthly cycle. |
| 403 | permission_denied | smart_pool_empty | rodiumai/smart found no eligible candidate inside the key's allowed_models (or provided-credit scope). | Widen allowed_models, or call a concrete model id. |
| 404 | invalid_request_error | model_not_found | Unknown or hidden model id. Also returned by GET /v1/models/{id} and GET /v1/pricing?model=; with a key, /v1/models/{id} returns 404 for models outside its allowed_models. | List valid ids with GET /v1/models. |
| 404 | invalid_request_error | previous_response_not_found | previous_response_id does not refer to a response created by your account through RodiumAI (param is previous_response_id). Nothing is billed. | Pass the id of a response you created through RodiumAI with the same account, or resend the conversation history instead. |
| 404 | invalid_request_error | profile_empty | A rule profile (rodium/basic, fast, pro, max, auto) has no active member allowed for this key. | Widen allowed_models, or call a concrete model id. |
| 404 | invalid_request_error | — | GET /v1/wallet found no RODI wallet for this credential (for example with an OIDC token, which spends FRODI). | Call /v1/wallet with an rd_sk_ API key. |
| 413 | payload_too_large | — | The request body exceeds 10 MiB. It is rejected before parsing. | Shrink base64 images or audio, send fewer images, or split the request. |
| 422 | — (detail[]) | — | POST /v1/audio/transcriptions: the multipart form lacks file or model, or a field has the wrong type. The body is {"detail": [...]}, not the error envelope. | Send multipart/form-data with file and model; detail[].loc names the field. |
| 429 | rate_limit_exceeded | rate_limit_exceeded | RPM, TPM or RPD limit reached for this key and model. Retry-After gives the wait in seconds. | Wait Retry-After seconds, then retry with jitter. See Rate limits. |
| 500 | server_error | — | The gateway could not verify the credential because of an internal fault. | Retry with backoff; contact support if it persists. |
| 500 | internal_error | — (request_id) | Unexpected gateway error. The body carries request_id instead of code and param. | Retry once with backoff, then send the request_id (also in the X-Request-Id response header) to support. |
| 503 | server_error | upstream_unsupported | The provider route serving this model cannot run this endpoint. | Try another model of the same modality. |
| 503 | server_error | model_unavailable | The model is temporarily disabled or has no active provider route. The message can be the catalogue notice, in English or French depending on Accept-Language. | Retry later or switch model. rodiumai_status is unavailable in GET /v1/models. |
| 503 | server_error | pricing_unavailable | The model's pricing configuration could not be loaded. | Retry with backoff; contact support if it persists. |
| 503 | server_error | billing_unavailable | The billing service could not reserve credits (transient). | Retry with backoff. Nothing was charged. |
| 503 | — (top-level code) | maintenance_active | Planned maintenance. The body is {"code", "scope", "message"} at the top level, not wrapped in error; message follows Accept-Language (en/fr). | Retry later with backoff. |
Errors from the model provider
When the provider behind a model fails, RodiumAI maps the failure to a stable status and code and removes provider details (names, account ids, URLs) from the message. These requests are not billed.
| HTTP | error.type | error.code | Cause | What to do |
|---|---|---|---|---|
| 400 | invalid_request_error | context_length_exceeded · content_policy_violation · unsupported_media · invalid_parameter · invalid_request | The provider rejected the request as invalid. The code says why: input over the context window, content policy, unreadable image / audio / file, or an invalid parameter; invalid_request when the reason is unknown. The message is relayed only for those categories, with provider names, ids and URLs removed; otherwise it is a fixed text. | Fix the request (shorten the input, adjust parameters, check media). Do not retry it unchanged. |
| 404 | invalid_request_error | not_found | The provider reported that a resource referenced by the request does not exist. | Check ids referenced in the request (files, previous responses…). |
| 413 | invalid_request_error | request_too_large | The provider found the request too large for this model. | Reduce the input or attachments, or choose a model with a larger limit. |
| 422 | invalid_request_error | unprocessable_request | The provider could not process the request content. | Check the request content; do not retry it unchanged. |
| 502 | server_error | provider_unavailable | The provider refused the call for an account, billing or permission reason on RodiumAI's side (provider 401/402/403). The message is generic. | Retry later or switch model. Your rd_sk_ key and your wallet are not the problem. |
| 429 | rate_limit_exceeded | rate_limit_exceeded | The provider throttled the request (provider 429). Generic message plus Retry-After. | Wait Retry-After seconds and retry with jitter, or use another model. |
| 502 | server_error | provider_unavailable | Provider outage (5xx) or network failure between RodiumAI and the provider. | Retry with exponential backoff; keep a fallback model ready. |
| 504 | server_error | timeout | The provider did not answer in time. | Retry, shorten the request or lower max_tokens; stream long generations. |
Handle by status class
502, 503 or 504 as retryable with backoff, 429 as retryable after Retry-After, and every other 4xx as a problem with the request, the key or the balance.Responses with a special shape
402: balance too low for the pre-flight hold
…429: rate limited (note Retry-After)
…500: unexpected error (note request_id)
…503: maintenance (not wrapped in error)
…413: body larger than 10 MiB
…422: transcription form validation
…Errors during a stream
Once a stream has started, the HTTP status is already 200, so failures arrive inside the stream. On /v1/chat/completions the gateway sends one data: event holding the usual error envelope, then data: [DONE]. Check every chunk for an error key.
…Provider errors in a stream are replaced by the same sanitised error as outside a stream (status class, code and message from the tables above), in the format of each API: /v1/responses sends an OpenAI Responses error event {"type": "error", "code", "message", "param"}; /v1/messages sends a native Anthropic event: error whose error.type is invalid_request_error, rate_limit_error or api_error.
/v1/responses
…/v1/messages
…How interrupted streams are billed is explained in Pricing and billing.
Anthropic Messages errors
On POST /v1/messages, body validation errors, provider errors and streaming errors use Anthropic's format so the Anthropic SDK raises its usual exceptions. Provider errors keep the statuses of the table above, with Anthropic types: rate_limit_error (429), invalid_request_error (400, 404, 413, 422) and api_error (502, 504). Errors raised before the call (authentication, balance, quota, rate limits) keep the OpenAI-style envelope. Anthropic SDKs pick the exception from the HTTP status, which is the same either way.
…Request ids
Every response carries an X-Request-Id header. Send your own (1 to 64 characters: letters, digits, -, _, .) to correlate with your logs; otherwise the gateway generates one. Quote it when you contact support. See the API overview.