Errors

Every 4xx and 5xx from the /v1 API uses one envelope, and it is the OpenAI-style envelope, so error handling you already wrote against the OpenAI SDK keeps working unchanged.

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "param": null,
    "code": "auth_error"
  },
  "request_id": "req_example_0000"
}

type is the broad family, code is the specific reason, and param names the request field when one caused it. Branch on type and code, never on message text. Some errors add fields directly inside error, such as paused_until, limit, or credit amounts, never nested under a details property. type is one of exactly six values.

`error.type`	Statuses that use it
`invalid_request_error`	400, 409, 413, 422
`authentication_error`	401
`permission_error`	402, 403
`not_found_error`	404
`rate_limit_error`	429
`api_error`	500, 502, 503, 504

There is no refusal without this envelope, including a failure we did not anticipate, which arrives as 500 internal_error rather than an empty body. The one exception is the platform edge rejecting a body far above the size limit before it reaches the gateway at all: that answers FUNCTION_PAYLOAD_TOO_LARGE in plain text, with no envelope and no request id. Every error response also carries X-Request-Id, matching request_id. Quote it when you contact support.

Should I retry?

The absence of the retry headers is a deliberate signal, not an oversight. A 400, 401, 402, 403, 404 or 413 needs a different request or different credentials, and 503 deployment_error needs a change to the deployment, so none of them carry timing.

Status and code reference

Status	`error.type`	`error.code`	What you should do
400	`invalid_request_error`	`invalid_json`	Send valid JSON.
400	`invalid_request_error`	`invalid_request`	Fix the field named by `param`.
400	`invalid_request_error`	`missing_required_field`	Add the field named by `param`.
400	`invalid_request_error`	`generation_count`	Reduce `n`, `best_of`, or another candidate-count field to four or fewer.
400	`invalid_request_error`	`total_output`	Reduce the total output budget across all generated choices.
400	`invalid_request_error`	`unsupported_model_operation`	Use an endpoint the selected model supports.
400	`invalid_request_error`	`hosted_capability_not_supported`	Drop the capability named by `param`, or call a model whose page lists it.
400	`invalid_request_error`	`hosted_parameter_not_supported`	Fix or remove the field named by `param`. When it is `response_format`, send `reasoning_effort: "none"` in the same request or drop the format.
400	`authentication_error`	`auth_error`	Use a workspace key with the flat `/v1` base URL, or the pipeline URL for a pipeline key.
401	`authentication_error`	`auth_error`	Send an active workspace API key in the Bearer header.
402	`permission_error`	`insufficient_credits`	Add enough credits for the reservation, then retry.
402	`permission_error`	`account_frozen`	Resolve the billing issue on the workspace, or add credits, then retry.
403	`authentication_error`	`auth_error`	Replace a CLI, internal, or deactivated key with an active workspace API key.
403	`permission_error`	`byoc_plan_required`	Call the deployment’s direct endpoint, or add credits to route it through the gateway again.
404	`not_found_error`	`model_not_found`	Call `GET /v1/models` and use an id returned for the same key.
409	`invalid_request_error`	`idempotency_conflict`	Wait for `Retry-After`, then retry with the same key and body.
413	`invalid_request_error`	`payload_too_large`	Reduce the JSON request body below 3.5MB.
422	`invalid_request_error`	`idempotency_replay_unavailable`	Do not switch to a new idempotency key. Contact support with the request id.
429	`rate_limit_error`	`rate_limit_exceeded`	Wait for `Retry-After`, the per-key window’s real reset time.
429	`rate_limit_error`	`hosted_per_key_concurrency_limit`	Wait for `Retry-After`. It clears when a request using this key finishes.
429	`rate_limit_error`	`hosted_workspace_concurrency_limit`	Wait for `Retry-After`. It clears when a hosted request in the workspace finishes.
429	`rate_limit_error`	`hosted_shared_model_concurrency_limit`	Wait for `Retry-After`. Contact support if saturation continues.
429	`rate_limit_error`	`hosted_workspace_tpm_limit`	Wait for `Retry-After`. When one request alone exceeds the limit no timing is sent, so reduce its token reservation.
429	`rate_limit_error`	`hosted_admission_congested`	Wait for `Retry-After`. The gateway shed the request under momentary load. It is not a quota.
429	`rate_limit_error`	`hosted_saturated_large_prompt`	The model is momentarily near its concurrency limit and requests with very large prompts are deferred first. Wait for `Retry-After` and retry unchanged; smaller prompts admit normally. It is not a size limit: the same request admits when load drops.
500	`api_error`	`internal_error`	Retry after `Retry-After`. Include `X-Request-Id` in a ticket if it persists.
500	`api_error`	`credit_reservation_failed`	The credit reservation could not be recorded. Retry after `Retry-After`.
502	`api_error`	`response_format_error`	Retry the request. Contact support if it continues.
502	`api_error`	`upstream_error`	The model upstream failed after dispatch. Retry after `Retry-After`.
502	`api_error`	`upstream_http_error`	The model upstream returned an HTTP failure. Retry after `Retry-After`.
504	`api_error`	`hosted_inference_response_timeout`	The response exceeded its deadline. Retry after `Retry-After`; for a non-streaming request, set `stream: true` or lower `max_tokens`.

Every 503 is in the table below.

The 503 codes

A 503 means a dependency the gateway needs was unreachable and it failed closed rather than serving unmetered or unbilled. All of them carry Retry-After except the last.

`error.code`	What happened
`hosted_model_paused`	The model is temporarily paused. `error.paused_until` carries the scheduled return, and `Retry-After` is capped at 60 seconds.
`limiter_unavailable`	The rate limiter could not be reached.
`hosted_admission_unavailable`	The capacity admission check could not complete.
`hosted_evidence_unavailable`	The usage record that must exist before serving could not be written. No charge is incurred.
`hosted_inference_unavailable`	No hosted upstream was available for this request. Retry after `Retry-After`.
`datastore_unavailable`	The datastore was unreachable, or it killed the statement. Congestion alone is not this error and answers `429` `hosted_admission_congested` instead.
`idempotency_unavailable`	The idempotency store could not be reached.
`billing_settlement_error`	Usage settlement did not complete.
`pricing_unavailable`	Pricing for the target could not be resolved.
`upstream_http_error`	The model upstream returned an HTTP failure. An authoritative upstream `Retry-After` is preserved; otherwise the gateway supplies a short fallback.
`deployment_error`	The resolved deployment cannot be served by this route. This one carries no retry timing, because it needs a look at the deployment rather than a wait.

Hosted-model catch-path 502, 503, and 504 responses also include error.runinfra. Its reason is upstream_error, upstream_unavailable, or deadline, and retryable is true. A non-streaming deadline includes structured remedies: enable stream: true, because response headers arrive with the first token, or use a smaller max_tokens value.

Envelopes that carry more than the table

402 insufficient_credits, with the balance and the top-up link

Credit fields are in cents. These values are an example.

{
  "error": {
    "current_balance_cents": 0,
    "required_cents": 1,
    "topup_url": "https://runinfra.ai/settings/cost#credits",
    "message": "Out of credits: balance $0.0000, required $0.0100. Add credits at https://runinfra.ai/settings/cost#credits to continue.",
    "type": "permission_error",
    "param": null,
    "code": "insufficient_credits"
  },
  "request_id": "req_example_0010"
}

Add at least required_cents - current_balance_cents, then retry. topup_url is absolute so it resolves from a terminal, an SDK exception, or a log line, none of which have an origin to resolve a relative path against.A free_window_ended_at field appears only when the model you called was on a promotional free window that closed within the last seven days, as a UTC RFC 3339 instant describing the same close the message states in words. When there is no recently closed window the field is absent rather than null, which is the usual case. The same field accompanies a 402 account_frozen under the same rule. A model’s price, and whether it is inside a free window, live on that model’s page, never here.

503 hosted_model_paused, with the scheduled return

{
  "error": {
    "paused_until": "2026-09-12T11:07:19.211Z",
    "message": "Nemotron 3.5 Lightning 30B is paused and is scheduled to return at 2026-09-12T11:07:19.211Z. You may retry in 60 seconds to check availability.",
    "type": "api_error",
    "param": null,
    "code": "hosted_model_paused"
  },
  "request_id": "req_example_0014"
}

Retry-After is in seconds and capped at 60, so a long pause never parks a client for hours. If the scheduled return has already passed, the status and code stay the same and only the message changes.A paused model is not a missing model. It still appears in GET /v1/models with availability: "paused", so treat this as retry and poll, never as a reason to drop the model id from your configuration.

422 idempotency_replay_unavailable, and why not to change the key

{
  "error": {
    "original_status": 200,
    "original_response_bytes": 25000000,
    "message": "The original response for this Idempotency-Key was too large to replay safely. Do not retry with a new key because that can start new paid work. Contact support with the request ID.",
    "type": "invalid_request_error",
    "param": "Idempotency-Key",
    "code": "idempotency_replay_unavailable"
  },
  "request_id": "req_example_0012"
}

X-RunInfra-Idempotent-Replay: unavailable

A new key here would start new inference work and a second charge. Contact support with request_id instead.

400 hosted_parameter_not_supported on response_format

{
  "error": {
    "message": "This model cannot enforce response_format while it is reasoning, so the reply would not match the format you asked for and the request would be billed anyway. Send \"reasoning_effort\": \"none\" together with response_format, or remove response_format.",
    "type": "invalid_request_error",
    "param": "response_format",
    "code": "hosted_parameter_not_supported"
  },
  "request_id": "req_example_0020"
}

Send the request again with reasoning_effort: "none" beside response_format, or drop the format. The rule is per model, and the affected models are named in what each model supports. Nothing is charged for the refusal, which is the point: the alternative is a 200 carrying a reply your parser rejects, billed in full.

429 hosted_admission_congested, a capacity shed

Under a momentary burst the gateway can shed a request before completing it, when it cannot obtain a datastore connection in time or a bounded lock wait expires. That is a temporary capacity condition, not an outage, so it answers 429.

{
  "error": {
    "message": "The gateway is at capacity and shed this request before completing it. This is a temporary condition on our side, not a problem with your request. Retry after the interval in the Retry-After header.",
    "type": "rate_limit_error",
    "param": null,
    "code": "hosted_admission_congested"
  },
  "request_id": "req_example_0018"
}

This answer applies on every /v1 route, so the same condition never surfaces as a different status elsewhere. The message varies with where the shed happened; the status, type and code do not. Unlike a hosted admission limit, a shed carries no limit field and no X-Hosted-Limit-Scope header, because there is no quota to size against.

401 or 403 on a key that looks correct

runinfra login creates a CLI key. It has the same rp_ prefix and 40 character body as a workspace API key and it cannot call the inference API, so it answers authentication_error with the message “This API key is internal and cannot be used for customer inference.” Create a workspace API key in Settings, API keys.A pipeline-scoped key on the flat /v1 base URL answers 400 auth_error, and the message names the pipeline URL to use instead. See Authentication.

Payload too large

The 3.5MB ceiling is enforced on the declared Content-Length and again while the body streams, so an understated Content-Length does not bypass it. It is a limit on the encoded request and is separate from the model context window: split the prompt across requests or send less context. Well above the limit, around 4MB and beyond, the platform edge rejects the request before the gateway sees it, with a plain-text FUNCTION_PAYLOAD_TOO_LARGE response carrying no JSON envelope and no request id. Treat it as the same instruction: shrink the body.

Retry rules

Keep the same Idempotency-Key when you retry, streaming or not.
Respect Retry-After, or Retry-After-Ms if your client reads it, on every response that carries them.
On the hosted admission 429 codes the value is an estimate, capped at 8 seconds, and it changes between refusals. Add jitter if many workers share one key.
Change the request or the credentials before retrying 400, 401, 402, 403, 404 or 413. They carry no timing, and that is the signal.
Do not replace the key after 422 idempotency_replay_unavailable.
A streaming retry is not replayed as a stream. The same key returns 409 while the original is open, then the terminal usage and cost as JSON once it settles, never the delivered tokens. See Idempotent retries.

Rate limits

What each 429 means, and how to back off.

Idempotent retries

Retry safely, streaming or not.

Troubleshooting

Symptom first, from the response you actually got.

Start here

Guides

API reference

Should I retry?

Status and code reference

The 503 codes

Envelopes that carry more than the table

Payload too large

Retry rules

Rate limits

Idempotent retries

Troubleshooting

​Should I retry?

​Status and code reference

​The 503 codes

​Envelopes that carry more than the table

​Payload too large

​Retry rules

​Related

Rate limits

Idempotent retries

Troubleshooting

Should I retry?

Status and code reference

The 503 codes

Envelopes that carry more than the table

Payload too large

Retry rules

Related