RouteMux Docs

Error reference

Look up RouteMux API and request-log errors by canonical code or stable RMX reference.

RouteMux errors have three identifiers with different jobs:

  • Code, such as BILLING_INSUFFICIENT_CREDITS, is the machine-readable value for program logic.
  • Reference, such as RMX-BILLING-5001, is the stable lookup number to search and share with support.
  • Request ID, returned as x-request-id and shown in Logs, identifies one occurrence of an error.

Branch on the canonical code, not on message. Messages can be localized or reworded. A reference links to this page with a permanent anchor, for example RMX-BILLING-5001.

Where errors appear

API errors keep the envelope used by the protocol family you called. OpenAI-compatible responses use error.code; Anthropic-compatible responses use error.code; Vertex-compatible responses use error.status. Request logs show the same canonical code and stable reference after legacy or provider-specific inputs have been normalized.

All entries below state the default HTTP status and billing outcome. If a stream fails after response headers were sent, its HTTP status may remain 200; use the error event's code and reference instead.

When contacting support, include the stable reference and the request ID. The reference says what happened; the request ID lets support find the exact request.

Response examples

The protocol envelope stays compatible with the endpoint you called, while the RouteMux descriptor carries the same code, reference, documentation_url, request_id, retry, and billing semantics everywhere.

OpenAI-compatible HTTP error

{
  "error": {
    "code": "MODEL_BUSY",
    "message": "The model has no capacity for this request right now. Wait a few seconds and retry, lengthening the wait after each failure. Switch models if you need a result sooner.",
    "reference": "RMX-MODEL-3006",
    "documentation_url": "https://routemux.com/docs/errors#rmx-model-3006",
    "request_id": "req_01K0EXAMPLEBUSY",
    "retry": {
      "retryable": true,
      "strategy": "BACKOFF",
      "retry_after_seconds": 5
    },
    "billing": {
      "status": "NOT_BILLED"
    },
    "type": "overloaded_error",
    "param": null
  }
}

Anthropic-compatible HTTP error

{
  "type": "error",
  "error": {
    "type": "billing_error",
    "code": "BILLING_INSUFFICIENT_CREDITS",
    "message": "The prepaid wallet does not have enough available credit for this request. Top up the wallet, then submit the request again.",
    "reference": "RMX-BILLING-5001",
    "documentation_url": "https://routemux.com/docs/errors#rmx-billing-5001",
    "request_id": "req_01K0EXAMPLECREDIT",
    "retry": {
      "retryable": false,
      "strategy": "TOP_UP"
    },
    "billing": {
      "status": "NOT_BILLED"
    }
  },
  "request_id": "req_01K0EXAMPLECREDIT"
}

Vertex-compatible HTTP error

{
  "error": {
    "code": 504,
    "status": "PROVIDER_TIMEOUT",
    "message": "The model service did not complete within the allowed time. Wait a few seconds and retry, lengthening the wait after each failure, or switch to another model.",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "PROVIDER_TIMEOUT",
        "domain": "routemux.com",
        "metadata": {
          "reference": "RMX-PROVIDER-6001",
          "documentation_url": "https://routemux.com/docs/errors#rmx-provider-6001",
          "request_id": "req_01K0EXAMPLETIMEOUT",
          "retryable": "true",
          "retry_strategy": "BACKOFF",
          "billing_status": "NOT_BILLED"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.Help",
        "links": [
          {
            "description": "RouteMux error RMX-PROVIDER-6001",
            "url": "https://routemux.com/docs/errors#rmx-provider-6001"
          }
        ]
      }
    ]
  }
}

SSE error after streaming has started

event: error
data: {"error":{"code":"PROVIDER_STREAM_INTERRUPTED","message":"The response stream ended because it could no longer be read. Wait a few seconds and send the request again; if it keeps happening, contact support with the request ID.","reference":"RMX-PROVIDER-6007","documentation_url":"https://routemux.com/docs/errors#rmx-provider-6007","request_id":"req_01K0EXAMPLESTREAM","retry":{"retryable":true,"strategy":"BACKOFF"},"billing":{"status":"NOT_BILLED"}}}

For SSE, an error after response headers have been sent is an event: error frame. The HTTP status may already be 200; branch on error.code, then inspect retry and billing. The stream-interruption example is NOT_BILLED; always treat the returned billing field and the final request log as authoritative.

Public response headers

Every HTTP error exposes the same lookup metadata in headers. Header names are case-insensitive.

HeaderMeaning
X-Request-IDIdentifies this occurrence; use it to open the matching request log.
X-RouteMux-Error-CodeCanonical machine-readable error code.
X-RouteMux-Error-ReferenceStable RMX-… lookup reference.
LinkCanonical error-documentation URL with rel="describedby".
Content-LanguageLanguage used for the public error message and documentation link.
X-RouteMux-Billedtrue, false, pending, or unknown.
Retry-AfterMinimum delay in seconds when the error defines one.
Cache-ControlAlways no-store for error responses.

Find the request in Logs

  1. Copy the X-Request-ID, canonical code, or RMX-… reference from the response.
  2. Open Console → Request logs and paste it into Request ID / error reference / code. A code is normalized to its stable reference automatically.
  3. Click the error shown in a log row to open this page at the exact reference. Open the row itself to see its action, retry policy, billing result, and request context.
  4. If you need support, share the stable reference and request ID together. Do not send an API key or raw provider response.

Error catalog

Search below by canonical code, RMX-… reference, title, or HTTP status. Search is case-insensitive and treats hyphens and underscores as equivalent separators.

115 matching errors

Authentication and access

27 errors

AUTH_REQUIRED

RMX-AUTH-1001 · Authentication required

HTTP 401

This operation requires an authenticated RouteMux account.

Origin
Your request or account
Phase
Authentication
Retry
After fixing authentication.
Billing
Not billed

What to do

Sign in, then repeat the operation.

AUTH_API_KEY_REQUIRED

RMX-AUTH-1002 · API key required

HTTP 401

The request did not include a supported API-key header.

Origin
Your request or account
Phase
Authentication
Retry
After fixing authentication.
Billing
Not billed

What to do

Send one valid key in the authorization header expected by your SDK.

AUTH_INVALID_API_KEY

RMX-AUTH-1003 · Invalid API key

HTTP 401

The supplied API key could not be validated.

Origin
Your request or account
Phase
Authentication
Retry
After fixing authentication.
Billing
Not billed

What to do

Check the key value or create a new key in Console.

AUTH_AMBIGUOUS_API_KEY

RMX-AUTH-1004 · Ambiguous API key

HTTP 400

Different credentials were sent in more than one API-key header.

Origin
Your request or account
Phase
Authentication
Retry
After correcting the request.
Billing
Not billed

What to do

Send the key in one header only, or make every accepted key header identical.

AUTH_API_KEY_INACTIVE

RMX-AUTH-1005 · API key inactive

HTTP 403

The API key exists but is disabled.

Origin
Your request or account
Phase
Authentication
Retry
After fixing authentication.
Billing
Not billed

What to do

Enable the key or use another active key.

AUTH_API_KEY_EXPIRED

RMX-AUTH-1006 · API key expired

HTTP 403

The API key is past its configured expiry time.

Origin
Your request or account
Phase
Authentication
Retry
After fixing authentication.
Billing
Not billed

What to do

Create or use a key whose expiry date is still valid.

AUTH_API_KEY_REVOKED

RMX-AUTH-1007 · API key revoked

HTTP 400

A revoked API key cannot be used or restored.

Origin
Your request or account
Phase
Authentication
Retry
After fixing authentication.
Billing
Not billed

What to do

Create a replacement key and update the client configuration.

AUTH_ACCOUNT_SUSPENDED

RMX-AUTH-1008 · Account suspended

HTTP 403

The account that owns this credential is not allowed to make requests.

Origin
Your request or account
Phase
Authentication
Retry
Contact support if the error persists.
Billing
Not billed

What to do

Contact RouteMux support for an account review.

AUTH_REQUEST_FAILED

RMX-AUTH-1009 · Authentication request failed

HTTP 400

The submitted authentication details could not be accepted.

Origin
Your request or account
Phase
Authentication
Retry
After correcting the request.
Billing
Not billed

What to do

Check the submitted details and account state, then try again.

AUTH_CREDENTIALS_INVALID

RMX-AUTH-1024 · Email or password is incorrect

HTTP 401

The email and password combination did not match an account.

Origin
Your request or account
Phase
Authentication
Retry
After fixing authentication.
Billing
Not billed

What to do

Re-enter the password, or sign in with a one-time code instead.

AUTH_EMAIL_ALREADY_REGISTERED

RMX-AUTH-1025 · Email is already registered

HTTP 409

An account already exists for this email address.

Origin
Your request or account
Phase
Authentication
Retry
After fixing authentication.
Billing
Not billed

What to do

Sign in with this email instead of creating a new account.

AUTH_EMAIL_NOT_VERIFIED

RMX-AUTH-1026 · Email is not verified yet

HTTP 403

The account exists but its email address has not been verified.

Origin
Your request or account
Phase
Authentication
Retry
After fixing authentication.
Billing
Not billed

What to do

Open the verification link sent to this address; check the spam folder if it has not arrived.

AUTH_EMAIL_INVALID

RMX-AUTH-1027 · Email address is not valid

HTTP 400

The submitted email address is not a valid address.

Origin
Your request or account
Phase
Authentication
Retry
After correcting the request.
Billing
Not billed

What to do

Correct the email address and submit it again.

AUTH_FORBIDDEN

RMX-AUTH-1010 · Authentication action forbidden

HTTP 403

The account is not allowed to perform this authentication action.

Origin
Your request or account
Phase
Authentication
Retry
Contact support if the error persists.
Billing
Not billed

What to do

Use an eligible account or contact support if this restriction is unexpected.

AUTH_TURNSTILE_REQUIRED

RMX-AUTH-1011 · Human verification required

HTTP 400

This authentication attempt requires a human-verification challenge.

Origin
Your request or account
Phase
Authentication
Retry
After correcting the request.
Billing
Not billed

What to do

Complete the verification challenge, then submit the request again.

AUTH_TURNSTILE_FAILED

RMX-AUTH-1012 · Human verification failed

HTTP 403

The human-verification result could not be accepted.

Origin
Your request or account
Phase
Authentication
Retry
After correcting the request.
Billing
Not billed

What to do

Start a new verification challenge and try again.

AUTH_SIGNUP_NOT_ALLOWED

RMX-AUTH-1013 · Sign-up not allowed

HTTP 403

This email address is not currently eligible to create an account.

Origin
Your request or account
Phase
Authentication
Retry
Contact support if the error persists.
Billing
Not billed

What to do

Use an eligible email address or contact support about access.

AUTH_DISPOSABLE_EMAIL

RMX-AUTH-1014 · Disposable email not accepted

HTTP 403

Disposable email addresses cannot be used to create an account.

Origin
Your request or account
Phase
Authentication
Retry
After correcting the request.
Billing
Not billed

What to do

Use a permanent personal or work email address.

AUTH_CSRF_TOKEN_MISSING

RMX-AUTH-1015 · Security token missing

HTTP 403

The Console request did not include the required CSRF token.

Origin
Your request or account
Phase
Authentication
Retry
After fixing authentication.
Billing
Not billed

What to do

Refresh the Console page and submit the operation again.

AUTH_ACCOUNT_PROVISIONING

RMX-AUTH-1016 · Account setup in progress

HTTP 401

The account is still being prepared and cannot serve this request yet.

Origin
RouteMux platform
Phase
Authentication
Retry
Yes — wait first, and lengthen the wait after each failure.
Billing
Not billed

What to do

Wait briefly and retry; contact support if setup does not finish.

AUTH_CSRF_TOKEN_INVALID

RMX-AUTH-1017 · Security token invalid

HTTP 403

The Console security token is missing, expired or does not match the current session.

Origin
Your request or account
Phase
Authentication
Retry
After fixing authentication.
Billing
Not billed

What to do

Refresh the Console page and submit the operation again.

AUTH_VERIFICATION_CODE_INVALID

RMX-AUTH-1018 · Verification code invalid

HTTP 422

The verification code is incorrect, expired or has already been consumed.

Origin
Your request or account
Phase
Authentication
Retry
After fixing authentication.
Billing
Not billed

What to do

Request a new verification code and enter the latest code.

AUTH_API_KEY_NOT_FOUND

RMX-AUTH-1019 · API key not found

HTTP 404

The requested API key does not exist or does not belong to this account.

Origin
Your request or account
Phase
Authentication
Retry
After correcting the request.
Billing
Not billed

What to do

Refresh the API-key list and use an identifier shown there.

AUTH_API_KEY_CONFIGURATION_INVALID

RMX-AUTH-1020 · API key configuration invalid

HTTP 400

One or more API-key settings, such as its name, expiry, models, quota, tags or rate-limit policy, are invalid.

Origin
Your request or account
Phase
Authentication
Retry
After correcting the request.
Billing
Not billed

What to do

Correct the highlighted API-key settings and submit them again.

AUTH_API_KEY_NOT_REVEALABLE

RMX-AUTH-1021 · API key cannot be revealed

HTTP 409

This older API key was created before secure plaintext recovery was available.

Origin
Your request or account
Phase
Authentication
Retry
After correcting the request.
Billing
Not billed

What to do

Create a replacement key, update your clients, then revoke the old key.

AUTH_SESSION_NOT_FOUND

RMX-AUTH-1022 · Session not found

HTTP 404

The requested sign-in session no longer exists or does not belong to this account.

Origin
Your request or account
Phase
Authentication
Retry
After correcting the request.
Billing
Not billed

What to do

Refresh the session list before trying the operation again.

AUTH_CURRENT_SESSION_REVOKE_FORBIDDEN

RMX-AUTH-1023 · Current session cannot be revoked here

HTTP 422

The session-management action cannot revoke the session currently making the request.

Origin
Your request or account
Phase
Authentication
Retry
After fixing authentication.
Billing
Not billed

What to do

Use Sign out to end the current session.

Request validation

12 errors

REQUEST_INVALID

RMX-REQUEST-2001 · Invalid request

HTTP 400

The request does not match what this endpoint expects.

Origin
Your request or account
Phase
Validation
Retry
After correcting the request.
Billing
Not billed

What to do

Correct the reported field or body shape before retrying.

REQUEST_MODEL_REQUIRED

RMX-REQUEST-2002 · Model required

HTTP 400

No model identifier was provided in the expected location.

Origin
Your request or account
Phase
Validation
Retry
After correcting the request.
Billing
Not billed

What to do

Set a published RouteMux model ID in the body or URL path.

REQUEST_TOO_LARGE

RMX-REQUEST-2003 · Request too large

HTTP 413

The complete request exceeds the gateway size limit.

Origin
Your request or account
Phase
Validation
Retry
After correcting the request.
Billing
Not billed

What to do

Reduce the request body or uploaded files, then send it again.

REQUEST_CONTENT_TOO_LARGE

RMX-REQUEST-2004 · Content too large

HTTP 413

One item in the request exceeds the size this endpoint allows.

Origin
Your request or account
Phase
Validation
Retry
After correcting the request.
Billing
Not billed

What to do

Shorten or compress the oversized content before retrying.

REQUEST_MEDIA_TYPE_UNSUPPORTED

RMX-REQUEST-2005 · Unsupported media type

HTTP 415

The endpoint cannot parse the submitted Content-Type or media format.

Origin
Your request or account
Phase
Validation
Retry
After correcting the request.
Billing
Not billed

What to do

Use one of the formats listed in the documentation for this endpoint.

REQUEST_CLIENT_DISCONNECTED

RMX-REQUEST-2006 · Client disconnected

HTTP 499

The client closed the connection before the response completed.

Origin
Your request or account
Phase
Streaming
Retry
Yes — submitting again is safe.
Billing
Not billed

What to do

Increase the client timeout or avoid cancelling long-running streams.

REQUEST_ROUTE_NOT_FOUND

RMX-REQUEST-2007 · Route not found

HTTP 404

The requested gateway path or method is not supported.

Origin
Your request or account
Phase
Validation
Retry
After correcting the request.
Billing
Not billed

What to do

Check the base URL, path and HTTP method against the API reference.

REQUEST_TIMEOUT

RMX-REQUEST-2008 · Request timed out

HTTP 408

The client stopped waiting before the operation completed.

Origin
Your request or account
Phase
Forwarding
Retry
Yes — submitting again is safe.
Billing
Not billed

What to do

Increase the client timeout or retry the request.

REQUEST_ABORTED

RMX-REQUEST-2009 · Request cancelled

HTTP 499

The client cancelled the operation before it completed.

Origin
Your request or account
Phase
Forwarding
Retry
Yes — submitting again is safe.
Billing
Not billed

What to do

Submit the request again only if the cancellation was unintended.

REQUEST_IDEMPOTENCY_IN_PROGRESS

RMX-REQUEST-2010 · Request already in progress

HTTP 409

Another request with the same idempotency key is still in progress.

Origin
Your request or account
Phase
Validation
Retry
Yes — wait first, and lengthen the wait after each failure.
Billing
Not billed

What to do

The original request is still running. Check its result shortly, or wait and retry with the same x-idempotency-key.

REQUEST_IDEMPOTENCY_CONFLICT

RMX-REQUEST-2011 · Idempotency key already used

HTTP 409

The idempotency key was already used for a request with different semantics.

Origin
Your request or account
Phase
Validation
Retry
After correcting the request.
Billing
Not billed

What to do

This x-idempotency-key was already used with different content. Use a new key when the operation, model or body changes.

REQUEST_IDEMPOTENCY_REPLAY_UNAVAILABLE

RMX-REQUEST-2012 · Idempotent response unavailable

HTTP 409

The original request reached a terminal state, but its response cannot be replayed.

Origin
Your request or account
Phase
Validation
Retry
After correcting the request.
Billing
Not billed

What to do

Check the original request in Logs first, then decide whether to resubmit with a new key.

Models and capabilities

17 errors

MODEL_NOT_FOUND

RMX-MODEL-3001 · Model not found

HTTP 404

The requested model is not present in the published RouteMux catalog.

Origin
Your request or account
Phase
Model routing
Retry
Use another model, or retry only when advised.
Billing
Not billed

What to do

Choose a model ID returned by the models endpoint.

MODEL_ACCESS_DENIED

RMX-MODEL-3002 · Model access denied

HTTP 403

The API key or account is not allowed to use this model.

Origin
Your request or account
Phase
Model routing
Retry
Use another model, or retry only when advised.
Billing
Not billed

What to do

Use an allowed model or update the key model restrictions.

MODEL_PROTOCOL_UNSUPPORTED

RMX-MODEL-3003 · Model protocol unsupported

HTTP 400

This model is not exposed through the protocol family used by the request.

Origin
Your request or account
Phase
Model routing
Retry
Use another model, or retry only when advised.
Billing
Not billed

What to do

Call an endpoint this model supports, or choose another model.

MODEL_UNAVAILABLE

RMX-MODEL-3004 · Model unavailable

HTTP 503

The selected model could not serve this request.

Origin
Model service
Phase
Model routing
Retry
Use another model, or retry only when advised.
Billing
Not billed

What to do

Try another model or retry later; contact support if it persists.

MODEL_NOT_PROVISIONED

RMX-MODEL-3005 · Model not provisioned

HTTP 503

The model exists in the catalog but is not currently enabled for serving.

Origin
RouteMux platform
Phase
Model routing
Retry
Use another model, or retry only when advised.
Billing
Not billed

What to do

Choose another model or contact support; unchanged retries will not help.

MODEL_BUSY

RMX-MODEL-3006 · Model busy

HTTP 503

The model has no capacity for this request right now.

Origin
Model service
Phase
Model routing
Retry
Yes — wait first, and lengthen the wait after each failure. Wait at least 5 seconds.
Billing
Not billed

What to do

Wait a few seconds and retry, lengthening the wait after each failure. Switch models if you need a result sooner.

MODEL_PARAMETER_UNSUPPORTED

RMX-MODEL-3016 · Parameter not accepted by this model

HTTP 400

One request parameter uses a value this model does not accept, or a value outside its allowed range.

Origin
Your request or account
Phase
Validation
Retry
After correcting the request.
Billing
Not billed

What to do

Check the model detail page for the accepted values and range of that parameter, then adjust it or choose another model.

MODEL_AUDIO_INPUT_UNSUPPORTED

RMX-MODEL-3015 · Audio input unsupported

HTTP 400

The selected model cannot process audio input.

Origin
Your request or account
Phase
Validation
Retry
Use another model, or retry only when advised.
Billing
Not billed

What to do

Remove the audio input or choose a model that accepts audio.

MODEL_VISION_UNSUPPORTED

RMX-MODEL-3007 · Vision unsupported

HTTP 400

The selected model cannot process image input.

Origin
Your request or account
Phase
Validation
Retry
Use another model, or retry only when advised.
Billing
Not billed

What to do

Remove the image input or choose a vision-capable model.

MODEL_IMAGE_TO_VIDEO_UNSUPPORTED

RMX-MODEL-3008 · Image-to-video unsupported

HTTP 400

The selected video model does not accept an initial image.

Origin
Your request or account
Phase
Validation
Retry
Use another model, or retry only when advised.
Billing
Not billed

What to do

Use text-only generation or select an image-to-video model.

MODEL_TEXT_TO_VIDEO_UNSUPPORTED

RMX-MODEL-3009 · Text-to-video unsupported

HTTP 400

The selected video model requires image input.

Origin
Your request or account
Phase
Validation
Retry
Use another model, or retry only when advised.
Billing
Not billed

What to do

Add the required image or choose a text-to-video model.

MODEL_LAST_FRAME_UNSUPPORTED

RMX-MODEL-3010 · Last frame unsupported

HTTP 400

The selected video model does not accept a last-frame constraint.

Origin
Your request or account
Phase
Validation
Retry
Use another model, or retry only when advised.
Billing
Not billed

What to do

Remove the last frame or choose a model that supports it.

MODEL_REFERENCE_IMAGE_UNSUPPORTED

RMX-MODEL-3011 · Reference image unsupported

HTTP 400

The selected model does not accept reference images.

Origin
Your request or account
Phase
Validation
Retry
Use another model, or retry only when advised.
Billing
Not billed

What to do

Remove reference images or choose a model that supports them.

MODEL_FIRST_FRAME_REQUIRED

RMX-MODEL-3012 · First frame required

HTTP 400

A last frame cannot be used without a first frame.

Origin
Your request or account
Phase
Validation
Retry
After correcting the request.
Billing
Not billed

What to do

Add a first frame or remove the last-frame input.

MODEL_SERVICE_TIER_UNAVAILABLE

RMX-MODEL-3013 · Service tier unavailable

HTTP 400

The requested service tier is not available for this model or account.

Origin
Your request or account
Phase
Model routing
Retry
After correcting the request.
Billing
Not billed

What to do

Remove the tier override or select an available tier.

MODEL_PUBLISH_PRICING_REQUIRED

RMX-MODEL-3014 · Model pricing required

HTTP 422

The model cannot be published until complete pricing is configured.

Origin
Your request or account
Phase
Console operation
Retry
After correcting the request.
Billing
Not billed

What to do

Complete every required pricing field, then publish again.

MODEL_CONTEXT_EXCEEDED

RMX-MODEL-3017 · Context window exceeded

HTTP 400

The input is larger than what this model can accept in one request.

Origin
Your request or account
Phase
Forwarding
Retry
After correcting the request.
Billing
Not billed

What to do

Shorten or compact the conversation history, or switch to a model with a larger context window. Retrying the same request will fail again.

Limits and quotas

3 errors

LIMIT_RATE_EXCEEDED

RMX-LIMIT-4001 · Rate limited

HTTP 429

A RouteMux request, concurrency or policy limit was reached.

Origin
Your request or account
Phase
Rate limiting
Retry
Yes — wait first, and lengthen the wait after each failure.
Billing
Not billed

What to do

Wait for the number of seconds in the Retry-After header before retrying. Without that header, wait a few seconds, then double the wait after each failure and add a small random delay so clients do not all retry at once.

LIMIT_API_KEY_QUOTA_EXHAUSTED

RMX-LIMIT-4002 · API key quota exhausted

HTTP 429

The API key reached its configured spending or usage quota.

Origin
Your request or account
Phase
Rate limiting
Retry
Contact support if the error persists.
Billing
Not billed

What to do

Raise the key quota, wait for its reset, or use another key.

LIMIT_API_KEY_POLICY_NOT_ALLOWED

RMX-LIMIT-4003 · API key limit policy not allowed

HTTP 403

An API key cannot be assigned a rate-limit policy above the account tier.

Origin
Your request or account
Phase
Rate limiting
Retry
After correcting the request.
Billing
Not billed

What to do

Choose an inherited policy or a tier no higher than the account tier.

Billing and wallet

25 errors

BILLING_INSUFFICIENT_CREDITS

RMX-BILLING-5001 · Insufficient credits

HTTP 422

The prepaid wallet does not have enough available credit for this request.

Origin
Your request or account
Phase
Billing admission
Retry
After topping up the wallet.
Billing
Not billed

What to do

Top up the wallet, then submit the request again.

Top up wallet

BILLING_BALANCE_LIMIT_REACHED

RMX-BILLING-5002 · Balance limit reached

HTTP 422

Admitting the request would exceed the wallet credit floor.

Origin
Your request or account
Phase
Billing admission
Retry
After topping up the wallet.
Billing
Not billed

What to do

Top up the wallet before sending more billable requests.

Top up wallet

BILLING_COUPON_INVALID

RMX-BILLING-5003 · Coupon invalid

HTTP 422

The coupon cannot be applied to this purchase.

Origin
Your request or account
Phase
Billing admission
Retry
After correcting the request.
Billing
Not billed

What to do

Check the code and eligibility, or continue without the coupon.

BILLING_COUPON_EXPIRED

RMX-BILLING-5004 · Coupon expired

HTTP 422

The coupon is past its valid redemption period.

Origin
Your request or account
Phase
Billing admission
Retry
After correcting the request.
Billing
Not billed

What to do

Use another active coupon or continue without one.

BILLING_COUPON_EXHAUSTED

RMX-BILLING-5005 · Coupon fully redeemed

HTTP 422

The coupon has reached its redemption limit.

Origin
Your request or account
Phase
Billing admission
Retry
After correcting the request.
Billing
Not billed

What to do

Use another coupon or continue without one.

BILLING_COUPON_UNAVAILABLE

RMX-BILLING-5006 · Coupon temporarily unavailable

HTTP 422

The coupon is temporarily reserved or cannot be applied right now.

Origin
Your request or account
Phase
Billing admission
Retry
Yes — wait first, and lengthen the wait after each failure.
Billing
Not billed

What to do

Wait briefly and retry, or use another coupon.

BILLING_PROMOTION_LIMIT_REACHED

RMX-BILLING-5007 · Promotion limit reached

HTTP 422

This account or promotion has reached its allowed benefit limit.

Origin
Your request or account
Phase
Billing admission
Retry
After correcting the request.
Billing
Not billed

What to do

Continue without the promotion or review its eligibility rules.

BILLING_COUPON_BELOW_MINIMUM

RMX-BILLING-5008 · Purchase below coupon minimum

HTTP 422

The payable amount does not meet the coupon minimum.

Origin
Your request or account
Phase
Billing admission
Retry
After correcting the request.
Billing
Not billed

What to do

Increase the top-up amount or remove the coupon.

BILLING_REDEEM_CODE_REQUIRED

RMX-BILLING-5009 · Redeem code required

HTTP 422

No redeem code was provided.

Origin
Your request or account
Phase
Billing admission
Retry
After correcting the request.
Billing
Not billed

What to do

Enter a redeem code and submit again.

BILLING_REDEEM_CODE_INVALID

RMX-BILLING-5010 · Redeem code invalid

HTTP 422

The redeem code is disabled, risky or otherwise invalid.

Origin
Your request or account
Phase
Billing admission
Retry
After correcting the request.
Billing
Not billed

What to do

Check the code or use another valid redeem code.

BILLING_REDEEM_CODE_EXPIRED

RMX-BILLING-5011 · Redeem code expired

HTTP 422

The redeem code is past its valid redemption period.

Origin
Your request or account
Phase
Billing admission
Retry
After correcting the request.
Billing
Not billed

What to do

Use another active redeem code.

BILLING_REDEEM_ALREADY_USED

RMX-BILLING-5012 · Redeem code already used

HTTP 409

The redeem code has already been claimed.

Origin
Your request or account
Phase
Billing admission
Retry
After correcting the request.
Billing
Not billed

What to do

Use another redeem code.

BILLING_REDEEM_LIMIT_REACHED

RMX-BILLING-5013 · Redeem limit reached

HTTP 422

This account has reached the per-user limit for the redeem code.

Origin
Your request or account
Phase
Billing admission
Retry
After correcting the request.
Billing
Not billed

What to do

Use a different eligible redeem code.

BILLING_REDEEM_NOT_REVERSIBLE

RMX-BILLING-5014 · Redeem cannot be reversed

HTTP 422

This redeem record is not in a reversible state.

Origin
Your request or account
Phase
Billing admission
Retry
After correcting the request.
Billing
Not billed

What to do

Refresh the record and verify its current state before retrying.

BILLING_REDEEM_RESOURCE_NOT_FOUND

RMX-BILLING-5015 · Redeem resource not found

HTTP 404

The requested redeem code or batch could not be found.

Origin
Your request or account
Phase
Billing admission
Retry
After correcting the request.
Billing
Not billed

What to do

Check the identifier and refresh the list.

BILLING_PRICING_STALE

RMX-BILLING-5016 · Pricing changed

HTTP 409

Pricing changed after the preview was created.

Origin
Your request or account
Phase
Billing admission
Retry
After correcting the request.
Billing
Not billed

What to do

Reload the latest pricing, review it and submit again.

BILLING_REFUND_TRANSACTION_NOT_FOUND

RMX-BILLING-5017 · Refund transaction not found

HTTP 404

No refundable transaction matches the supplied identifier.

Origin
Your request or account
Phase
Billing admission
Retry
After correcting the request.
Billing
Not billed

What to do

Check the transaction or payment intent and refresh the history.

BILLING_COUPON_CODE_CONFLICT

RMX-BILLING-5018 · Coupon code already exists

HTTP 409

Another coupon already uses this code.

Origin
Your request or account
Phase
Billing admission
Retry
After correcting the request.
Billing
Not billed

What to do

Choose a different coupon code and submit again.

BILLING_COUPON_NOT_FOUND

RMX-BILLING-5019 · Coupon not found

HTTP 404

The requested coupon record could not be found.

Origin
Your request or account
Phase
Billing admission
Retry
After correcting the request.
Billing
Not billed

What to do

Check the identifier and refresh the coupon list.

BILLING_CONFIGURATION_INVALID

RMX-BILLING-5020 · Billing configuration invalid

HTTP 422

A top-up amount, package, payment option, alert, auto-top-up or webhook setting is invalid or incomplete.

Origin
Your request or account
Phase
Billing admission
Retry
After correcting the request.
Billing
Not billed

What to do

Review the billing form values and required settings, then submit it again.

BILLING_PAYMENT_METHOD_REQUIRED

RMX-BILLING-5021 · Payment method required

HTTP 422

This billing feature requires a saved payment method.

Origin
Your request or account
Phase
Billing admission
Retry
After correcting the request.
Billing
Not billed

What to do

Add a payment card before enabling this feature.

BILLING_PAYMENT_PENDING

RMX-BILLING-5022 · Payment still pending

HTTP 409

An unfinished payment prevents this account operation from continuing safely.

Origin
Your request or account
Phase
Billing admission
Retry
After correcting the request.
Billing
Not billed

What to do

Complete or cancel the pending payment before trying the account operation again.

BILLING_PAYMENT_RESOURCE_NOT_FOUND

RMX-BILLING-5023 · Payment resource not found

HTTP 404

The requested checkout receipt or billing-customer record could not be found for this account.

Origin
Your request or account
Phase
Billing admission
Retry
After correcting the request.
Billing
Not billed

What to do

Check the receipt link and refresh billing history; top up first if the account has no payment history.

BILLING_REFUND_AMOUNT_INVALID

RMX-BILLING-5024 · Refund amount invalid

HTTP 422

The refund amount is missing, outside the allowed range or exceeds the remaining refundable amount.

Origin
Your request or account
Phase
Billing admission
Retry
After correcting the request.
Billing
Not billed

What to do

Enter a positive amount within the refundable balance shown in billing history.

BILLING_REFUND_NOT_AVAILABLE

RMX-BILLING-5025 · Refund not available

HTTP 422

The payment or its remaining credit is not in a state that can be refunded.

Origin
Your request or account
Phase
Billing admission
Retry
Contact support if the error persists.
Billing
Not billed

What to do

Refresh billing history and review the payment state; contact support if it should still be refundable.

Model service and network

8 errors

PROVIDER_TIMEOUT

RMX-PROVIDER-6001 · Provider timeout

HTTP 504

The model service did not complete within the allowed time.

Origin
Model service
Phase
Forwarding
Retry
Yes — wait first, and lengthen the wait after each failure.
Billing
Not billed

What to do

Wait a few seconds and retry, lengthening the wait after each failure, or switch to another model.

PROVIDER_UNREACHABLE

RMX-PROVIDER-6002 · Provider unreachable

HTTP 502

RouteMux could not establish a connection to the model service.

Origin
Model service
Phase
Forwarding
Retry
Yes — wait first, and lengthen the wait after each failure.
Billing
Not billed

What to do

Wait a few seconds and retry, lengthening the wait after each failure, or use another model.

PROVIDER_RATE_LIMITED

RMX-PROVIDER-6003 · Provider rate limited

HTTP 429

The model service rejected the request because its current limit was reached.

Origin
Model service
Phase
Forwarding
Retry
Yes — wait first, and lengthen the wait after each failure.
Billing
Not billed

What to do

Wait, then retry with a longer delay after each failure, or choose another model.

PROVIDER_REQUEST_REJECTED

RMX-PROVIDER-6004 · Provider rejected request

HTTP 400

The model service considered the forwarded request invalid.

Origin
Model service
Phase
Forwarding
Retry
After correcting the request.
Billing
Not billed

What to do

Review model-specific parameters and correct the request before retrying.

PROVIDER_UNAVAILABLE

RMX-PROVIDER-6005 · Provider unavailable

HTTP 502

The model service could not process this request.

Origin
Model service
Phase
Forwarding
Retry
Yes — wait first, and lengthen the wait after each failure.
Billing
Not billed

What to do

Wait a few seconds and retry, or switch models; include the request ID if contacting support.

PROVIDER_HTTP_ERROR

RMX-PROVIDER-6006 · Provider HTTP error

HTTP 502

The model service returned an error status without a safer specific classification.

Origin
Model service
Phase
Forwarding
Retry
Yes — wait first, and lengthen the wait after each failure.
Billing
Not billed

What to do

If the status is 5xx, wait a few seconds and retry. If it is 4xx, the request itself needs fixing and retrying will not help.

PROVIDER_STREAM_INTERRUPTED

RMX-PROVIDER-6007 · Provider stream interrupted

HTTP 502

The response stream ended because it could no longer be read.

Origin
Model service
Phase
Streaming
Retry
Yes — wait first, and lengthen the wait after each failure.
Billing
Not billed

What to do

Wait a few seconds and send the request again; if it keeps happening, contact support with the request ID.

PROVIDER_OVERLOADED

RMX-PROVIDER-6008 · Provider overloaded

HTTP 503

The model service is temporarily overloaded and rejected this request.

Origin
Model service
Phase
Forwarding
Retry
Yes — wait first, and lengthen the wait after each failure.
Billing
Not billed

What to do

This is temporary. Wait 30-60 seconds and retry, lengthening the wait after each failure, or switch to another model.

Jobs and generated media

11 errors

JOB_NOT_FOUND

RMX-JOB-7001 · Job not found

HTTP 404

The requested asynchronous job does not exist or is no longer available.

Origin
Asynchronous job
Phase
Job processing
Retry
After correcting the request.
Billing
Not billed

What to do

Check the job ID and account, then submit a new job if needed.

JOB_VIDEO_NOT_READY

RMX-JOB-7002 · Video not ready

HTTP 409

The video job is still running and has no downloadable result yet.

Origin
Asynchronous job
Phase
Job processing
Retry
Yes — wait first, and lengthen the wait after each failure.
Billing
Not billed

What to do

Wait before polling the job again.

JOB_WORKER_STOPPED

RMX-JOB-7003 · Job worker stopped

HTTP 500

The worker processing the asynchronous job stopped responding.

Origin
Asynchronous job
Phase
Job processing
Retry
Yes — submitting again is safe.
Billing
Not billed

What to do

Submit the job again; contact support if this repeats.

JOB_RESULT_LOST

RMX-JOB-7004 · Job result unavailable

HTTP 500

The asynchronous result could not be recovered after processing.

Origin
Asynchronous job
Phase
Job processing
Retry
Yes — submitting again is safe.
Billing
Not billed

What to do

Submit the job again and contact support with the request ID if needed.

JOB_ARTIFACT_NOT_FOUND

RMX-JOB-7005 · Artifact not found

HTTP 404

The requested generated file is missing, expired or unavailable.

Origin
Asynchronous job
Phase
Job processing
Retry
Yes — submitting again is safe.
Billing
Not billed

What to do

Check the artifact URL or create a new generation.

JOB_VIDEO_GENERATION_FAILED

RMX-JOB-7006 · Video generation failed

HTTP 502

The video job ended without a usable result.

Origin
Asynchronous job
Phase
Job processing
Retry
Yes — submitting again is safe.
Billing
Not billed

What to do

Retry the job or choose another model.

JOB_IMAGE_GENERATION_FAILED

RMX-JOB-7007 · Image generation failed

HTTP 502

The image generation ended without a usable result.

Origin
Asynchronous job
Phase
Job processing
Retry
Yes — submitting again is safe.
Billing
Not billed

What to do

Retry the request or choose another model.

JOB_MUSIC_GENERATION_FAILED

RMX-JOB-7008 · Music generation failed

HTTP 502

The music generation ended without a usable result.

Origin
Asynchronous job
Phase
Job processing
Retry
Yes — submitting again is safe.
Billing
Not billed

What to do

Retry the job or choose another model.

JOB_SERVICE_DISABLED

RMX-JOB-7009 · Async jobs unavailable

HTTP 503

Asynchronous gateway jobs are not enabled in this environment.

Origin
RouteMux platform
Phase
Job processing
Retry
Contact support if the error persists.
Billing
Not billed

What to do

Use a synchronous endpoint instead, or contact support.

JOB_NOT_CANCELLABLE

RMX-JOB-7011 · Job can no longer be cancelled

HTTP 409

The job already left the queue, so cancellation no longer applies. This is not a failure of the job itself.

Origin
Asynchronous job
Phase
Job processing
Retry
No — retrying unchanged will not help.
Billing
Not billed

What to do

Poll the job for its current state; a running job runs to completion and a finished job needs no cancellation.

JOB_FAILED

RMX-JOB-7010 · Job failed

HTTP 500

The asynchronous job failed without a safer specific classification.

Origin
Asynchronous job
Phase
Job processing
Retry
Yes — submitting again is safe.
Billing
Not billed

What to do

Retry the job; include the request ID if contacting support.

Console operations

7 errors

CONSOLE_REQUEST_FAILED

RMX-CONSOLE-8001 · Console request failed

HTTP 400

A Console operation failed without a public specific classification.

Origin
Your request or account
Phase
Console operation
Retry
Contact support if the error persists.
Billing
Not billed

What to do

Retry once, then contact support with the request ID if it persists.

CONSOLE_PLAYGROUND_DISABLED

RMX-CONSOLE-8002 · Playground unavailable

HTTP 503

Playground is not enabled in this environment.

Origin
RouteMux platform
Phase
Console operation
Retry
Contact support if the error persists.
Billing
Not billed

What to do

Use the API directly or contact support about availability.

CONSOLE_CONFIRMATION_REQUIRED

RMX-CONSOLE-8003 · Confirmation required

HTTP 409

This high-impact change requires an explicit confirmation.

Origin
Your request or account
Phase
Console operation
Retry
After correcting the request.
Billing
Not billed

What to do

Review the warning and confirm the change if it is intended.

CONSOLE_STALE_UPDATE

RMX-CONSOLE-8004 · Record changed

HTTP 409

The record was modified after this edit began.

Origin
Your request or account
Phase
Console operation
Retry
After correcting the request.
Billing
Not billed

What to do

Reload the latest record, review the changes and submit again.

CONSOLE_RESOURCE_NOT_FOUND

RMX-CONSOLE-8005 · Console resource not found

HTTP 404

The requested Console resource no longer exists or does not belong to this account.

Origin
Your request or account
Phase
Console operation
Retry
After correcting the request.
Billing
Not billed

What to do

Refresh the relevant list and open a resource shown there.

CONSOLE_LOG_RECORD_NOT_FOUND

RMX-CONSOLE-8006 · Log record not found

HTTP 404

No retained log record matches this identifier for the current account.

Origin
Your request or account
Phase
Console operation
Retry
After correcting the request.
Billing
Not billed

What to do

Check the request ID or reference and search the Logs page again.

CONSOLE_LOG_RECORD_EXPIRED

RMX-CONSOLE-8007 · Log record expired

HTTP 410

The log record previously existed but was deleted after its retention period ended.

Origin
Your request or account
Phase
Console operation
Retry
Contact support if the error persists.
Billing
Not billed

What to do

Use another retained record or contact support with any request details you still have.

Platform and settlement

5 errors

PLATFORM_USAGE_UNSETTLED

RMX-PLATFORM-9001 · Usage not settled

HTTP 500

The request did not reach a final settlement state before reconciliation closed it.

Origin
RouteMux platform
Phase
Settlement
Retry
Yes — submitting again is safe.
Billing
Not billed

What to do

Retry the request and contact support if this repeats.

PLATFORM_USAGE_UNPARSED

RMX-PLATFORM-9002 · Usage could not be read

HTTP 500

RouteMux could not read the usage values required for settlement.

Origin
RouteMux platform
Phase
Settlement
Retry
Yes — submitting again is safe.
Billing
Not billed

What to do

Retry or contact support with the model and request ID.

PLATFORM_USAGE_INTERRUPTED

RMX-PLATFORM-9003 · Usage processing interrupted

HTTP 500

Platform processing stopped while the request was still in progress.

Origin
RouteMux platform
Phase
Settlement
Retry
Yes — submitting again is safe.
Billing
Not billed

What to do

Retry the request; contact support if interruptions cluster together.

PLATFORM_PRICING_INCOMPLETE

RMX-PLATFORM-9004 · Pricing incomplete

HTTP 500

The request completed but required pricing data was missing.

Origin
RouteMux platform
Phase
Settlement
Retry
Contact support if the error persists.
Billing
Not billed

What to do

Contact support with the model and request ID; unchanged retries will not help.

PLATFORM_INTERNAL_ERROR

RMX-PLATFORM-9005 · Platform error

HTTP 500

RouteMux could not complete the operation and no safer specific code is available.

Origin
RouteMux platform
Phase
Settlement
Retry
Contact support if the error persists.
Billing
Not billed

What to do

Retry once, then contact support with the request ID if it persists.

Observability & usage

Inspect logs, usage trends, latency, and per-request charges.

Handling errors

Decide what to do next from retry.strategy, retry.retryable and billing.status instead of hard-coding a branch per error code.

On this page

Where errors appearResponse examplesPublic response headersFind the request in LogsError catalog