Errors

RightNow AI Decision model Errors Updated 2026-11-12

View as Markdown

On this page

Error body
Error codes
Retries
Get help

Use error.code to identify a refusal and error.retryable to decide whether to retry.

Status

Error body

A request refusal returns an HTTP status and an error envelope. This example shows an unsupported input refusal.

error.json

JSON

{
  "error": {
    "message": "The document format is not supported.",
    "type": "invalid_request_error",
    "param": "attachments[0].data",
    "code": "document_unsupported",
    "retryable": false
  },
  "request_id": "request-id-from-response"
}

error.message: A readable description of the refusal.
error.type: The error category.
error.param: The affected field, or null.
error.code: The code your application should handle.
error.retryable: A boolean: true permits an automatic retry; false stops automatic retries.
error.details: Optional machine-readable context, such as a cause or reset.
request_id: The request identifier to include when contacting support.

An HTTP 200 can contain a refusal under an individual question in answers. Check the entries as well as the HTTP status.

Read the flag
x-should-retry matches error.retryable. True permits a retry. False stops it.
False includes 504 system_zero_timeout.
Read the wait
Wait Retry-After-Ms, or Retry-After when it is absent.
The SDK and the Manual HTTP example stop on a wait over 60 seconds. Maintenance waits 240 to 360 seconds.
Send it again
Keep the same Idempotency-Key and JSON body.
If the first try finished, its stored answer can return in place of new work.
Stop at the bound
The SDK makes at most 5 retries on a 60 second retry budget. The Manual HTTP example resends for 10 minutes.

Retry or stop: read the flag, then the wait.

Error codes

400 media_unsupported: Audio must be WAV (PCM or float) at a 16,000 Hz sample rate. Other audio formats are unsupported.

For a PDF, follow the matching document refusal below. Read Inputs for document limits. A priced PDF can still fail its page range, decoded size, encryption, source, signature or structure checks. Malformed data URLs are refused before PDF validation.

Document case	Status and code	Reason	Message and action
Non-PDF document	`415 document_unsupported`	`pdf_required`	PDF is supported. Export this document to PDF and send the PDF file. Send the exported PDF inline.
PDF page range	`403 media_unpriced`	No specific reason	This input type is not supported. Send a PDF within the published physical page range.
Decoded PDF size	`413 document_too_large`	No specific reason	The document exceeds the decoded byte limit. Keep the decoded files within the request byte budget.
Encrypted PDF	`403 media_unpriced`	`pdf_encrypted`	Encrypted PDFs are not supported. Export an unencrypted PDF and send it again. Send the unencrypted PDF inline.
Document upload reference	`400 media_unsupported`	No specific reason	Field: `attachments[i].upload`. The media kind or count is not supported. At most 4 images and 1 audio are allowed. Send PDF data inline; upload references are not available to outside callers today.
Invalid PDF signature	`415 document_unsupported`	No specific reason	Field: `attachments[0].data`. The document format is not supported. The declared PDF bytes fail the signature check. Send a valid PDF.
Malformed data URL	`400 invalid_request`	No specific reason	The request is invalid. Correct the data URL before sending the inline PDF.
Malformed PDF structure	`403 media_unpriced`	No specific reason	This input type is not supported. The signature passed, but the PDF structure is invalid. Export a valid PDF.

Status	Code	Meaning	Retryable
400	Code: `idempotency_key_reuse`	Type: invalid_request_error. This idempotency key already settled another request. Use the original body with this key, or use a new key for changed work.	No automatic retry.
400	Code: `invalid_idempotency_key`	Type: invalid_request_error. Use a nonblank `Idempotency-Key` with valid ASCII characters within the accepted length.	No automatic retry.
400	Code: `invalid_request`	Type: invalid_request_error. The request is invalid. Correct the JSON, field names, types or encoding before resending.	No automatic retry.
400	Code: `invalid_trace_header`	Type: invalid_request_error. Correct or remove `X-Client-Request-Id`; its value must be nonblank ASCII within the accepted length.	No automatic retry.
400	Code: `media_unsupported`	Type: invalid_request_error. The media kind or count is not supported. At most 4 images and 1 audio are allowed. An attachment type, format or count is not supported. Held upload references return 400 media_unsupported at attachments[i].upload. Send files inline.	No automatic retry.
400	Code: `long_state_unsupported`	Held feature. Type: invalid_request_error. This input combination is not supported. This input combination is not supported.	No automatic retry.
400	Code: `webhook_invalid`	Type: invalid_request_error. The webhook request is invalid. The URL, events, limit or body is invalid, or `Idempotency-Key` was sent.	No automatic retry.
401	Code: `invalid_api_key`	Type: authentication_error. Authorization is missing, malformed or unknown; a Playground credential is not accepted as a public bearer key. Use a valid API key.	No automatic retry.
402	Code: `insufficient_credits`	Type: permission_error. The workspace's balance does not cover this call. Add funds before starting a new request. Read balance_cents, required_cents and add_funds_url in error.details.	No automatic retry.
402	Code: `spend_limit_reached`	Type: permission_error. This API key has reached its monthly spending limit. A workspace owner or admin can raise or remove it under Settings, API keys, or wait until resets_at. This request was not charged. Raise or remove the key's limit, or wait for resets_at. Read limit_cents, spent_cents and resets_at in error.	No automatic retry.
403	Code: `account_suspended`	Type: permission_error. The account is suspended, blocked or waiting for access. Contact support.	No automatic retry.
403	Code: `auth_error`	Type: authentication_error. The API key is revoked or blocked. Replace the key; this response uses authentication_error as its type.	No automatic retry.
403	Code: `https_required`	Type: invalid_request_error. This API answers only over HTTPS. Send the request to the https address. Use the HTTPS base URL.	No automatic retry.
403	Code: `media_unpriced`	Type: permission_error. This input type is not supported. The input format has no published price. Use a priced format listed in Inputs.	No automatic retry.
403	Code: `starter_credit_held`	Type: permission_error. Your starting credit is under review. Contact us to request a review. Starting credit is under review. Contact us to request a review.	No automatic retry.
404	Code: `audio_not_available`	Type: not_found_error. Audio is unavailable. Send the request without the audio attachment. This release can refuse an unavailable route or input. Audio combined with images, PDFs or video is unavailable. Run the audio on its own.	No automatic retry.
404	Code: `committee_not_available`	Held feature. Type: not_found_error. This route is not available. Use standard route.	No automatic retry.
404	Code: `deliberate_not_available`	Held feature. Type: not_found_error. This mode is not available. Use standard mode.	No automatic retry.
404	Code: `document_controls_not_available`	Held feature. Type: not_found_error. Documents with control characters are unavailable. Remove the control characters and send it again. Remove control characters from the document and send it again.	No automatic retry.
404	Code: `document_not_available`	Type: not_found_error. Documents are unavailable. Send the request without the document attachment. Send document contents as state text without an attachment.	No automatic retry.
404	Code: `document_pictures_not_available`	Held feature. Type: not_found_error. Pictures inside documents are unavailable. Send the document without pictures, or as text. Send the document without pictures, or send its contents as state text.	No automatic retry.
404	Code: `image_not_available`	Type: not_found_error. Images are unavailable. Send the request without the image attachment. This release can refuse an unavailable route or input.	No automatic retry.
404	Code: `long_context_not_available`	Type: not_found_error. This route is not available. Check the access steps in Danger zone, or send a shorter request.	No automatic retry.
404	Code: `long_recording_not_available`	Held feature. Type: not_found_error. This input type is not supported. Remove the long recording.	No automatic retry.
404	Code: `model_not_found`	Type: not_found_error. The requested model is not offered. Choose the alias or an available pinned version.	No automatic retry.
404	Code: `unknown_endpoint`	Type: not_found_error. The route is unavailable. Check the base URL and path; this response does not mean the API key is invalid.	No automatic retry.
404	Code: `video_not_available`	Type: not_found_error. This input type is not supported. An unavailable video route was refused. Production serves inline H.264 MP4 video as a preview.	No automatic retry.
404	Code: `decision_not_found`	Type: not_found_error. The requested decision is not available. The id is invalid, or no stored decision matches it for this API key.	No automatic retry.
404	Code: `upload_not_found`	Held feature. Type: not_found_error. The requested item is not available to this account. The requested item is not available to this account.	No automatic retry.
404	Code: `session_not_found`	Held feature. Type: not_found_error. The requested resource is not available to this account. The requested resource is not available to this account.	No automatic retry.
404	Code: `unknown_state`	Held feature. Type: not_found_error. The requested state is not available. The requested state is not available.	No automatic retry.
404	Code: `webhook_not_found`	Type: not_found_error. The requested webhook is not available to this workspace. The endpoint is absent or belongs to another workspace.	No automatic retry.
405	Code: `method_not_allowed`	Type: invalid_request_error. Use a method from the Allow response header.	No automatic retry.
409	Code: `idempotency_conflict`	Type: invalid_request_error. The same key and body is still running. Wait and retry with that key.	Yes. Follow the response wait.
409	Code: `idempotency_replay_unavailable`	Type: invalid_request_error. The request completed, but the stored answer is unavailable. details.original_status records the original status. A new key starts new work; this is not a replay of the old answer.	No automatic retry.
409	Code: `upload_not_ready`	Held feature. Type: invalid_request_error. The requested item is not ready. The requested item is not ready.	No automatic retry.
409	Code: `upload_in_use`	Held feature. Type: invalid_request_error. The requested item is in use by another request. The requested item is in use by another request.	Yes. Follow the response wait.
409	Code: `stale_parent`	Held feature. Type: invalid_request_error. The parent is not the latest state. The parent is not the latest state.	No automatic retry.
409	Code: `session_busy`	Held feature. Type: invalid_request_error. Another request is still using this resource. Another request is still using this resource.	Yes. Follow the response wait.
409	Code: `session_limit`	Held feature. Type: invalid_request_error. This account has reached its concurrency limit. This account has reached its concurrency limit.	No automatic retry.
409	Code: `op_conflict`	Held feature. Type: invalid_request_error. This op_id was already used with a different append or rewind. Send a new op_id. This op_id was already used with a different append or rewind. Send a new op_id.	No automatic retry.
410	Code: `session_lost`	Held feature. Type: invalid_request_error. The requested resource is no longer available. The requested resource is no longer available.	No automatic retry.
413	Code: `payload_too_large`	Type: invalid_request_error. The request exceeds the body limit. Send fewer or smaller attachments. Reduce the whole request body.	No automatic retry.
413	Code: `questions_too_large`	Type: invalid_request_error. The questions exceed the reply or token limit. Send fewer or shorter questions. Send fewer or shorter questions.	No automatic retry.
413	Code: `state_too_large`	Type: invalid_request_error. The state exceeds the size or nesting limit. Shorten the state or reduce nesting.	No automatic retry.
413	Code: `media_too_large`	Type: invalid_request_error. The media exceeds the decoded byte limit. Media takes the attachments over the decoded size limit.	No automatic retry.
413	Code: `document_too_large`	Type: invalid_request_error. The document exceeds the decoded byte limit. A document takes the attachments over the decoded size limit.	No automatic retry.
413	Code: `attachment_too_large`	Held feature. Type: invalid_request_error. This input exceeds the supported limits. This input exceeds the supported limits.	No automatic retry.
413	Code: `long_duration_unsupported`	Held feature. Type: invalid_request_error. This input exceeds the supported limits. This input exceeds the supported limits.	No automatic retry.
413	Code: `long_too_many_phrases`	Held feature. Type: invalid_request_error. This request exceeds the supported limits. This request exceeds the supported limits.	No automatic retry.
415	Code: `document_unsupported`	Type: invalid_request_error. The document format is not supported. A document's format is not supported, or its bytes do not match it.	No automatic retry.
421	Code: `wrong_host`	Held feature. Type: invalid_request_error. This route is not available for this request. This route is not available for this request.	No automatic retry.
422	Code: `injection_suspected`	Type: invalid_request_error. The request was refused because its content reads as instructions to the model. Remove the embedded instructions and send it again. Remove embedded instructions from the input and send changed input.	No automatic retry.
422	Code: `input_quarantined`	Type: invalid_request_error. This exact input caused repeated serving failures, so it is refused for up to 24 hours. Change the input or contact support. Do not resend the same input in a loop.	No automatic retry.
422	Code: `invalid_criteria`	Type: invalid_request_error. The question criteria are invalid. Use the supported criteria shape and the option and level counts in the model list's limits.	No automatic retry.
422	Code: `question_too_large`	Type: invalid_request_error. The question exceeds the size limit. Shorten the affected question.	No automatic retry.
422	Code: `request_refused`	Type: invalid_request_error. RightNow refused this request. Change it before sending it again. Review the state and question instructions before starting new work.	No automatic retry.
422	Code: `workspace_quarantined`	Type: invalid_request_error. This account's requests are paused for up to an hour after repeated serving failures. Contact support. Stop dispatching work from this workspace while the pause is in effect.	No automatic retry.
422	Code: `media_decode_failed`	Type: invalid_request_error. The media bytes do not match the declared format. Media bytes do not match the declared format.	No automatic retry.
422	Code: `document_decode_failed`	Type: invalid_request_error. The document could not be decoded. A document could not be decoded.	No automatic retry.
422	Code: `question_not_grounded`	Type: invalid_request_error. The question cannot be answered from this state. The question cannot be answered from this state.	No automatic retry.
422	Code: `upload_invalid`	Held feature. Type: invalid_request_error. This input does not match its declared size, type or hash. This input does not match its declared size, type or hash.	No automatic retry.
422	Code: `long_question_unsupported`	Held feature. Type: invalid_request_error. This question cannot be answered for this input. This question cannot be answered for this input.	No automatic retry.
422	Code: `long_options_unsupported`	Held feature. Type: invalid_request_error. These options cannot be evaluated for this input. These options cannot be evaluated for this input.	No automatic retry.
422	Code: `long_phrase_invalid`	Held feature. Type: invalid_request_error. This phrase cannot be evaluated for this input. This phrase cannot be evaluated for this input.	No automatic retry.
422	Code: `long_question_type_unsupported`	Held feature. Type: invalid_request_error. This question type cannot be answered for this input. This question type cannot be answered for this input.	No automatic retry.
422	Code: `long_media_guard_refused`	Held feature. Type: invalid_request_error. This input was refused. This input was refused.	No automatic retry.
422	Code: `long_no_readable_window`	Held feature. Type: invalid_request_error. This input could not be read. This input could not be read.	No automatic retry.
422	Code: `long_evidence_incomplete`	Held feature. Type: invalid_request_error. This input could not be read completely. This input could not be read completely.	No automatic retry.
429	Code: `capacity_exhausted`	Type: overloaded_error. RightNow is at capacity. Retry after the `Retry-After` delay. Wait for `Retry-After`; retry only with bounded client backoff.	Yes. Follow the response wait.
429	Code: `concurrency_limit_exceeded`	Type: rate_limit_error. This account has reached its concurrent call limit. Retry after the `Retry-After` delay. The account already has its allowed work in flight. Follow `Retry-After` and reduce concurrency; details include max_concurrent.	Yes. Follow the response wait.
429	Code: `daily_dispatch_limit`	Type: rate_limit_error. This account reached today's request limit. It resets at 00:00 UTC. Wait until the UTC reset named by the response.	Yes. Follow the response wait.
429	Code: `daily_unbilled_limit`	Type: rate_limit_error. This workspace reached today's unanswered processing limit. It resets at 00:00 UTC. Wait until the UTC reset named by the response.	Yes. Follow the response wait.
429	Code: `monthly_cap_reached`	Type: rate_limit_error. The workspace reached its monthly decision cap. Follow resets_at and `Retry-After`; details include monthly_request_cap and used.	Yes. Follow the response wait.
429	Code: `playground_daily_limit`	Type: rate_limit_error. The Playground reached its daily limit. Wait for resets_at; details include daily_limit.	Yes. Follow the response wait.
429	Code: `rate_limit_exceeded`	Type: rate_limit_error. Too many requests from this key or address. Retry after the `Retry-After` delay. Wait for `Retry-After` and pace requests to the returned limits.	Yes. Follow the response wait.
429	Code: `workspace_limit_exceeded`	Type: rate_limit_error. This workspace is over one of its own allowances, such as calls in flight or bytes being read. Retry after the `Retry-After` delay. Wait for `Retry-After` and reduce the workspace's concurrent work or input load.	Yes. Follow the response wait.
429	Code: `upload_quota_exhausted`	Held feature. Type: rate_limit_error. This account has reached a supported limit. This account has reached a supported limit.	Yes. Follow the response wait.
429	Code: `sessions_at_capacity`	Held feature. Type: overloaded_error. No capacity is available right now. No capacity is available right now.	Yes. Follow the response wait.
429	Code: `session_hours_exhausted`	Held feature. Type: rate_limit_error. This account has exhausted its daily allowance. The account reached its daily session limit. Wait until the next UTC day.	Yes. Follow the response wait.
429	Code: `starter_spend_limit`	Type: rate_limit_error. This request exceeds the starting credit spend allowance. Retry after the `Retry-After` delay or request a review. Follow `Retry-After` or request a review of the starting credit spend limit.	Yes. Follow the response wait.
429	Code: `starter_rate_limit`	Type: rate_limit_error. Starting credit requests reached their rate allowance. Retry after the `Retry-After` delay. Follow `Retry-After` before sending more starting credit requests.	Yes. Follow the response wait.
429	Code: `starter_concurrency_limit`	Type: rate_limit_error. Two starting credit requests are already in progress. Retry after the `Retry-After` delay. Starting credit requests already occupy the available concurrency. Follow `Retry-After`.	Yes. Follow the response wait.
429	Code: `starter_attempt_limit`	Type: rate_limit_error. Starting credit processing reached its temporary allowance. Retry after the `Retry-After` delay. Follow `Retry-After` before processing more starting credit requests.	Yes. Follow the response wait.
429	Code: `webhook_limit_exceeded`	Type: rate_limit_error. This workspace has reached its webhook endpoint limit. The workspace already has 5 endpoints. Delete an endpoint before creating another.	No automatic retry.
500	Code: `internal_error`	Type: api_error. An unexpected failure was caught. Retry after the stated delay; contact support with the request ID if it persists.	Yes. Follow the response wait.
503	Code: `idempotency_unavailable`	Type: api_error. Replay protection cannot answer. Retry with the same `Idempotency-Key` after the wait.	Yes. Follow the response wait.
503	Code: `limiter_unavailable`	Type: api_error. The limiting service cannot answer. Retry after the stated delay.	Yes. Follow the response wait.
503	Code: `maintenance`	Type: api_error. The API is in maintenance. Wait for `Retry-After`.	Yes. Follow the response wait.
503	Code: `service_unavailable`	Type: api_error. RightNow cannot serve this request right now. Retry after the `Retry-After` delay. Wait for `Retry-After`; keep the request ID if the failure persists. An admission store timeout returns 503 service_unavailable. Wait for `Retry-After` and `Retry-After-Ms` before retrying.	Yes. Follow the response wait.
503	Code: `system_zero_unavailable`	Type: api_error. RightNow is temporarily unavailable. Wait for `Retry-After` and retry when retryable is true.	Yes. Follow the response wait.
503	Code: `starter_unavailable`	Type: api_error. Starting credit enforcement is temporarily unavailable. Retry after the `Retry-After` delay. Starting credit enforcement is temporarily unavailable. Follow `Retry-After`.	Yes. Follow the response wait.
503	Code: `webhook_unavailable`	Type: overloaded_error. Webhook management is temporarily unavailable. Webhook management storage or encryption is unavailable.	Yes. Follow the response wait.
504	Code: `system_zero_timeout`	Type: api_error. RightNow exceeded the response deadline. Shorten the work or inspect the outcome; do not automatically replay unchanged.	No automatic retry.

Stream refusals, such as 429 stream_limit_exceeded, are listed under Streaming errors.

A call without an API key returns 401 invalid_api_key. Check the key, workspace access, API host and route.

A request over its cost cap returns 400 policy_max_cost_exceeded. It is not counted or charged, and error.retryable is false.

Retries

x-should-retry matches error.retryable. Stop automatic retries when it is false, including 504 system_zero_timeout.

When a response permits a retry, wait for Retry-After-Ms in milliseconds or Retry-After in seconds. Prefer Retry-After-Ms when both are present.

A rate_limit_exceeded refusal with error.details.cause set to replay_bytes means: Your account has used today's allowance for replayed answers. A request that repeats an Idempotency-Key gets its stored answer back, and those replays are limited by total bytes per account per UTC day. Replays resume at the next UTC day; the Retry-After headers give the wait.

Gateway 429 and 503 refusals carry Retry-After in whole seconds, rounded up, and Retry-After-Ms with the exact wait in milliseconds, except webhook_limit_exceeded.

Maintenance returns 503 with Retry-After and Retry-After-Ms. Each answer draws a wait of about 5 minutes (4 to 6), uniformly from 240 to 360 whole seconds.

A key-store outage returns 503 service_unavailable, which is retryable. Wait for Retry-After and Retry-After-Ms before retrying.

Keep the decision's Idempotency-Key and JSON body. An idempotency_conflict means the same work is still running; wait before retrying with that key.

A cold start is a model pool replacing its warm container after a crash, a recycle, a preemption or a deploy, or adding one under a burst. A cold start can outlast a client's retry window; follow the response flags and wait.

See the first request.

Get help

For a refusal that persists, use Contact and include the response's X-Request-Id.