Errors

Every error carries a code. Search this page for yours. Seeing 5xx errors or timeouts? Check status.flexinference.com first.

Find your code

Class	What it means	Retry the same request?
validation	Something in the request is wrong.	No
authentication	A key is missing, wrong, or rejected.	No
permission	The key is fine. This request isn’t allowed.	No
billing	Your balance ran out.	No
quota	You hit a rate, concurrency, or spend ceiling.	Yes, after a wait
capability	This model or route can’t do what you asked.	No
upstream	The fault is between us and the provider.	Yes
internal	The fault is on our side.	Yes
canceled	You went away before the response finished.	No

Every error body carries the same machine-readable block, described in the error body. One case returns 200 with the failure inside the body. See a stream that fails after it starts.

validation

Something in the request is wrong. Fix it and resend.

Code	Status	What it means and what to do
`invalid_json`	`400`	The body isn’t valid JSON. The usual cause is a trailing comma or an unquoted key.
`invalid_body`	`400`	The body parsed, but it isn’t a JSON object. Wrap your fields in one `{...}`.
`missing_model`	`400`	The `model` field is missing, empty, or not a string. Send something like `"model": "gpt-5.5"`.
`missing_start_within`	`400`	The request has no `start_within`, and your key carries no default for it. It sets how long you’ll wait for the request to start. Use `default`, `priority`, `auto`, or a duration like `00h-00m-30s`.
`invalid_start_within`	`400`	`start_within` isn’t one of the four accepted forms, or the duration is outside 5 to 600 seconds. `"00h-00m-30s"` is thirty seconds; `"default"` skips the race.
`invalid_stream`	`400`	`stream` isn’t a boolean. Send `"stream": true` or leave it out.
`invalid_retry`	`400`	`retry` is malformed. It’s an object like `{"count": 2}`. `count` is 1 to 5 and sets how many times we re-hit the tier on a transient 429 or 5xx. Optional: `backoff` (`"exponential"` or `"linear"`) and `jitter` (boolean). `error.message` names the exact fault.
`invalid_provider_chain`	`400`	The `provider` array is empty, too long, or holds a duplicate or unknown name. Valid names are `openai`, `anthropic`, `google`, `vertex`, `bedrock`, `foundry`, `cloudflare`, and `deepinfra`. Element 0 runs first and the rest are fallbacks. Drop the field for the model’s native route.
`service_tier_not_allowed`	`400`	The request set `service_tier`. We set the tier from `start_within`, so remove `service_tier` and say it there instead.
`key_default_not_applicable`	`400`	Your request left a field out, our key default filled it in, and validation refused the combination. The message names the field and the value. Send the field in the body (the body always wins), or edit the key defaults under API -> FlexInference keys.
`request_too_large`	`413`	The body is over 50 MB, and the usual cause is a large inline base64 file. Shrink it, or point to a hosted URL.
`model_not_found`	`404`	You asked `GET /v1/models/{id}` for an id we don’t list for your key. Call `GET /v1/models` to see your ids.
`previous_response_not_found`	`404`	A continuation named a response id your organization has no record of. Chain only on an id we returned to you (on managed keys ours start with `resp_fx_`), copied exactly. Drop the field to start fresh.
`unknown_url`	`404`	The path doesn’t exist. Use `/v1/responses`, `/v1/chat/completions`, `/v1/interactions`, `/v1/messages`, `/v1beta/models/{model}:generateContent`, or `/model/{modelId}/converse`. Streaming siblings are `:streamGenerateContent?alt=sse` and `/converse-stream`. The catalog is `GET /v1/models`.
`method_not_allowed`	`405`	The path exists but the method is wrong. Every serving endpoint takes `POST`. The model catalog is the one `GET`.
`cloudflare_upstream_rejected`	`400`	Workers AI refused the request shape, and we pass its explanation through. The usual cause is a message order the chat template forbids, like a user turn right after a tool result.

authentication

A key is missing, wrong, or refused. It’s either your FlexInference key or a provider key you stored.

Code	Status	What it means and what to do
`missing_api_key`	`401`	The request has no `Authorization` header, or it isn’t `Bearer <key>`.
`malformed_api_key`	`401`	The key isn’t shaped like a FlexInference key (`flex_live_` plus 24 hex characters plus a 6-character checksum), so we didn’t look it up. The usual cause is a truncated copy, a stray space or quote, or a key from another service. Copy it again.
`invalid_api_key`	`401`	The key is shaped right but matches nothing on record. The usual cause is a regenerated or mistyped key. Copy the current one from API -> FlexInference keys.
`revoked_api_key`	`401`	An org admin revoked this key, and revocation is permanent. Create a new key and send that.
`key_record_unreadable`	`500`	We found your key’s record and couldn’t read it. Your key is fine; this is our fault. Retry in a few minutes, and contact support if it persists.
`byok_key_undecryptable`	`500`	We couldn’t decrypt a provider key your organization stored. Saving that provider key again under API -> Provider keys clears it.
`no_byok_key`	`400`	Your organization stores no OpenAI key. Add one under API -> Provider keys. Every route you name in a `provider` chain needs its own key.
`no_gemini_key`	`400`	Your organization stores no Gemini key, and the request named a `gemini-*` model. Add one under API -> Provider keys.
`no_anthropic_key`	`400`	Your organization stores no Anthropic key, and the request named a `claude-*` model. Add one under API -> Provider keys.
`no_bedrock_key`	`400`	Your organization stores no Bedrock key, and the `provider` chain names `bedrock`. Add one under API -> Provider keys.
`no_vertex_key`	`400`	Your organization stores no Vertex key, and the chain names `vertex`. Vertex takes a Google express key, which starts with `AQ.`. Add it under API -> Provider keys.
`no_foundry_key`	`400`	Your organization stores no Foundry key, and the chain names `foundry`. Add the Azure key and resource name under API -> Provider keys.
`no_deepinfra_key`	`400`	Your organization stores no DeepInfra token, and the chain names `deepinfra`. Add it under API -> Provider keys.
`no_cloudflare_key`	`400`	Your organization stores no Cloudflare key, and the request needs the `cloudflare` route. Add one under API -> Provider keys.
`upstream_auth_failed`	`403`	The provider rejected the key your organization stored for it. Your FlexInference key is fine; that stored key expired or got revoked. Ask an org admin to update it under API -> Provider keys. `error.flexinference.provider` names the route.

permission

Your key is valid, and this request still isn’t allowed. Adding funds doesn’t clear these.

Code	Status	What it means and what to do
`account_under_review`	`403`	A risk check paused managed access for your organization. Your own key routes keep working. Contact support.
`payment_disputed`	`403`	A card payment was disputed, so serving stopped (own key routes too). Withdraw the dispute with your bank, or contact support.
`moderation_blocked`	`403`	The moderation pre-pass called this request harmful. It only runs when your organization turns moderation on, or when the request sends `moderate: true`. Revise the prompt, or contact support if the flag is wrong.
`bedrock_model_access_denied`	`403`	Amazon Bedrock refused the model for the AWS account behind your key. Grant the model in the Bedrock console under Model access. The newest Claude models also need a one-time account setup.

billing

Your balance ran out.

Code	Status	What it means and what to do
`insufficient_balance`	`402`	Your managed balance no longer covers the request. Add funds on the Billing page and resend.

quota

You hit a ceiling. The same request can succeed after a wait.

Code	Status	What it means and what to do
`rate_limit_exceeded`	`429`	Too many requests from your key, IP, or organization, or too many flex races in flight at once. Back off for the seconds in `Retry-After`.
`spend_velocity_exceeded`	`429`	You hit your daily managed-spend limit. Wait for the UTC day to roll over, or ask an org admin to request a higher limit.
`cloudflare_capacity`	`429`	Workers AI is at capacity. Nothing is wrong with your request. Wait briefly and resend, or try another open-source model.
`race_budget_exhausted`	`429`	Your workspace opted out of the standard-rate fallback for Claude races, and the race budget has no margin left. Wait for the next recompute, or send `start_within: "default"` for a standard serve.

capability

This model or route can’t do what you asked. Something in the request has to change.

Code	Status	What it means and what to do
`unsupported_parameter`	`400`	A native field reached the wrong provider. Chat fields work on OpenAI models and Anthropic fields on Claude models, and each fails anywhere else. Drop the field named by `error.param`, or pick a model whose provider owns it. See what passes through.
`unsupported_value`	`400`	Chat Completions `n` was set to something other than `1`. We always produce one generation. Send `"n": 1` or leave it out.
`unsupported_tool`	`400`	The `tools` array holds a built-in tool that makes the model emit something other than text (currently `image_generation`). We serve text only. Function tools and `web_search` work fine.
`unsupported_media_type`	`400`	An attached file uses a media type the model can’t read. Images must be JPEG, PNG, GIF, or WebP. Documents must be PDF. `error.param` is `image` or `input_file`.
`unsupported_generation_config`	`400`	A `generation_config.*` field with no mapping was sent to a non-Gemini model on `/v1/interactions`. Remove it, or target a Gemini model.
`gemini_search_function_conflict`	`400`	Gemini forbids a built-in tool and function tools in the same request. Send one or the other, or split them across two requests.
`auto_unsupported_for_gemini`	`400`	You sent `start_within: "auto"` to a Gemini model, and Gemini has no auto tier. Use `default`, `priority`, or a duration.
`model_not_carried`	`400`	We don’t carry this model, on your own keys or managed. Check the name against `GET /v1/models`.
`flex_unsupported_for_anthropic`	`400`	You sent a duration `start_within` to a `claude-*` model on your own Anthropic key. We race Claude’s cheaper tier on managed keys only. Use `default`, `priority`, or `auto`, or switch Anthropic to managed. See Flex racing with Claude models.
`flex_anthropic_streaming_unsupported`	`400`	You sent a duration `start_within` plus `stream: true` to a `claude-*` model. Claude’s cheaper tier returns one complete message, so a win can’t stream. Drop `stream` to race, or keep streaming with a tier.
`flex_anthropic_deadline_too_short`	`400`	You sent a duration under 180 seconds to a `claude-*` model, and a Claude race needs at least three minutes. Ask for `00h-03m-00s` or more, or send a tier.
`flex_model_not_capable`	`400`	You sent a duration `start_within` to an OpenAI or Gemini model that isn’t on the flex list. Use a tier, or a flex-capable model.
`flex_unsupported_on_cloud`	`400`	You sent a duration `start_within` with a cloud route first in the chain, and `vertex`, `bedrock`, and `foundry` have no flex tier to race. Use `"start_within": "default"`, or put `openai` or `google` first.
`tier_unsupported_on_cloud`	`400`	You sent `priority` or `auto` with a cloud route first in the chain, and cloud routes serve the provider default tier only. Use `"start_within": "default"`, or put a direct route first.
`tier_unsupported_on_managed`	`400`	You sent `priority` or `auto` on managed keys, and managed serving offers `default` or a flex duration. Switch that provider to your own key to use the premium tiers.
`provider_model_mismatch`	`400`	A route in the `provider` chain can’t serve this model. `openai` and `foundry` serve GPT models, `google` and `vertex` serve Gemini, `anthropic` and `bedrock` serve Claude. Remove the route that doesn’t match.
`bedrock_model_unavailable`	`400`	Amazon Bedrock has no id for this model, so the `bedrock` route can’t run it. Remove `bedrock` from the chain, or use a model it carries.
`model_not_priced_for_managed`	`400`	A managed request named a model with no published rate. Pick a priced model, or switch the provider to your own key.
`managed_family_restricted`	`400`	Managed Bedrock serves Claude models only and managed Vertex serves Gemini only. Pick a model in that route’s family, another route, or your own key.
`cloudflare_upstream_client_error`	`400`	Workers AI refused the request and the cause is permanent (a wrong request, an unknown model, or an oversized body). Fix the request, or use a direct provider.
`foundry_model_unavailable`	`404`	Azure AI Foundry doesn’t carry this model on your resource (its instant-access catalog is a subset of GPT models that changes over time). Remove `foundry` from `provider`, pick a model it carries, or create a deployment on your Azure resource.

upstream

The fault is between us and the provider. Nothing is wrong with your request.

Code	Status	What it means and what to do
`upstream_unavailable`	`502`	We couldn’t open a connection to the provider. Retry once. If one model keeps failing, the provider may be down, so try another model.
`upstream_stream_failed`	`502`	The provider started a response and then its stream stopped, with no completion and no error to pass through. Retry once. On a stream that had already started, this arrives in the body.
`upstream_error`	`502`	The provider answered HTTP 500 with no error code. `error.message` keeps the provider’s own text. Retry once.
`stream_idle_timeout`	`504`	The provider stopped feeding an open stream. Whatever text you received is the whole answer. Retry once.
`upstream_timeout`	`504`	The provider didn’t start responding before our timeout. It’s almost always a passing slowdown. Retry once.
`all_routes_failed`	`502`	Every route in your `provider` chain failed transiently (a 429, a 5xx, or a timeout), so no fallback was left. Retry once. If it persists, cut the chain down to healthy routes.
`cloudflare_upstream_error`	`502`	Workers AI reported an internal error. The fault is on Cloudflare’s side. Retry once, or try another open-source model.
`managed_upstream_unavailable`	`502`	Our own managed connection to the provider is briefly unavailable. The failing key is ours, not yours. Retry shortly, and contact support if it keeps happening.

internal

The fault is on our side. A repeat is worth reporting.

Code	Status	What it means and what to do
`internal_error`	`500`	Your request was valid and we still failed. Retry once, and contact support with the approximate time if it persists.
`limits_unavailable`	`503`	`GET /v1/limits` couldn’t read your records. Serving is unaffected. Retry in a few seconds.
`server_misconfigured`	`500`	Our deployment is misconfigured. Retry shortly, and contact support if it persists.
`pii_masking_failed`	`500`	PII masking failed, so we stopped the request. Retry once, or send `pii_mask: false` to run this one request unmasked.

canceled

You went away before the response finished.

Code	Status	What it means and what to do
`client_closed_request`	`499`	Your client disconnected first (a closed tab, a cancelled fetch, or a client-side timeout). If you didn’t mean to cancel, raise your client timeout. A flex request can take up to 10 minutes.

The provider array pins your route. openai, anthropic, google, cloudflare, and deepinfra are direct routes. vertex, bedrock, and foundry run the same models through Google Vertex AI, Amazon Bedrock, and Azure AI Foundry on your own cloud key. See backup providers.

The error body

Errors come in the shape of the endpoint you called. The OpenAI endpoints return the OpenAI shape and /v1/messages returns the Anthropic shape. The Google paths return the Google shape and the Converse paths return the AWS shape. Provider errors follow the same rule.

OpenAI shape (/v1/responses, /v1/chat/completions)

{
  "error": {
    "message": "The upstream provider rejected the API key your organization stored for it ...",
    "type": "permission_error",
    "code": "upstream_auth_failed",
    "param": null,
    "doc_url": "https://docs.flexinference.com/errors#upstream_auth_failed",
    "flexinference": {
      "code": "upstream_auth_failed",
      "class": "authentication",
      "origin": "provider",
      "status": 403,
      "provider": "openai",
      "provider_code": null,
      "retryable": false,
      "doc_url": "https://docs.flexinference.com/errors#upstream_auth_failed"
    }
  }
}

Anthropic shape (/v1/messages)

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "...",
    "flexinference": { "...": "..." }
  }
}

Google shape (/v1/interactions, :generateContent)

{
  "error": {
    "code": 401,
    "message": "...",
    "status": "UNAUTHENTICATED",
    "flexinference": { "...": "..." }
  }
}

AWS shape (/model/{modelId}/converse)

{
  "message": "...",
  "flexinference": { "...": "..." }
}

On the OpenAI shape, type uses the stock OpenAI categories plus two of ours. billing_error means a managed balance ran out, and flexinference_error means an internal or upstream fault. The AWS shape has no error wrapper. Its type goes in the x-amzn-errortype header.

The flexinference block

Every error carries one flexinference object, the same on all six endpoints.

Field	Meaning
`code`	Our code for this failure, from the tables above. `null` when a provider error passed through.
`class`	Which of the nine groups above this failure falls in.
`origin`	`flexinference` when we made the decision. `provider` when the provider did.
`status`	The status this failure carries. It matches the HTTP status, except on a stream that had already started.
`provider`	Which provider or route the failure is about, such as `openai` or `bedrock`. `null` when no single route applies.
`provider_code`	Whatever code the provider sent, when we passed one through.
`retryable`	`true` when the same request could succeed later. `false` when something has to change first.
`doc_url`	Deep link to this code’s row above. `null` for a provider error.

Branch on error.flexinference.code (or flexinference.code on the AWS shape). It’s the same value on all six endpoints, while the stock error.code exists on the OpenAI shape only. Treat an unknown code as an ordinary error of its class.

A stream that fails after it starts

A streaming response returns 200 as soon as the first bytes leave. HTTP gives no way to take that back. So a failure after that point reaches you in the body, not in the status. The stream ends with a terminal error event in your endpoint’s shape. It carries the same flexinference block a refused request has. Its status field says what the failure would have returned before the stream started. A streamed generateContent call ends with the Google error body as its last chunk. A converse-stream call ends with an event-stream exception frame (what the AWS SDKs raise on). Your SDK raises on that event. None of them hand you the flexinference block though, so read the raw event to get the code. The chunks that arrived before the raise are the whole answer. The dashboard logs the request as failed with this code, not as the 200 that went out first.

Provider errors

A provider error keeps its status and message and comes back in your endpoint’s shape. Call /v1/messages with an OpenAI model and its error comes back Anthropic-shaped. A passed-through provider error carries the block too, with origin reading provider and their code in provider_code.

Flex outcome headers

Successful 200 responses carry these on every endpoint, streaming or not.

Header	Meaning
`x-flexinference-flex-requested`	`true` when you sent a duration `start_within`; `false` on `default`, `priority`, or `auto`.
`x-flexinference-flex-applied`	`true` only when the flex tier served the response.
`x-flexinference-flex-reason`	Machine-readable outcome. Values below.
`x-flexinference-provider-surface`	Which provider wire ran it: `openai.responses`, `openai.chat`, `gemini.interactions`, or `anthropic.messages`. Not always your endpoint (a `/v1/chat/completions` call usually runs on `openai.responses`).
`x-flexinference-cost`	Provider cost of this serve as a micro-USD integer, the same value as `usage.cost.total_micro_usd`. Non-streaming only, and only when the serve can be priced. A streamed response reports cost on its usage frame instead, with `include_cost: true`. See cost inside a stream.

x-flexinference-flex-reason values:

Reason	Meaning
`not_requested`	You sent `default`, `priority`, or `auto`, so there was no race.
`flex_committed`	The discounted tier served it. The body shows `service_tier: "flex"`, or `"batch"` on a Claude win.
`flex_lost_race`	You sent a duration and the discounted tier didn’t make it, so standard served at the standard price.

A duration that can’t race at all returns 400 instead: flex_model_not_capable off the flex list, flex_unsupported_for_anthropic on your own Anthropic key, flex_anthropic_streaming_unsupported with stream: true, and flex_anthropic_deadline_too_short under 180 seconds.

Handling errors in code

OpenAI SDKs raise on non-2xx responses and attach the parsed body.

from openai import APIStatusError

try:
    resp = client.responses.create(
        model="gpt-5.5",
        input="hi",
        extra_body={"start_within": "00h-00m-30s"},
    )
except APIStatusError as e:
    code = (e.body or {}).get("error", {}).get("flexinference", {}).get("code")
    if code == "no_byok_key":
        print("Add your OpenAI key in the dashboard.")
    else:
        raise

import OpenAI from "openai";

try {
  await client.responses.create({
    model: "gpt-5.5",
    input: "hi",
    start_within: "00h-00m-30s",
  } as any);
} catch (e) {
  if (e instanceof OpenAI.APIError && e.code === "no_byok_key") {
    console.log("Add your OpenAI key in the dashboard.");
  } else {
    throw e;
  }
}

Get started

Concepts

Additional Features

Using the API

Agent Keys + Integrations

Find your code

validation

authentication

permission

billing

quota

capability

upstream

internal

canceled

The error body

The flexinference block

A stream that fails after it starts

Provider errors

Flex outcome headers

Handling errors in code

​Find your code

​validation

​authentication

​permission

​billing

​quota

​capability

​upstream

​internal

​canceled

​The error body

​The flexinference block

​A stream that fails after it starts

​Provider errors

​Flex outcome headers

​Handling errors in code

Find your code

validation

authentication

permission

billing

quota

capability

upstream

internal

canceled

The error body

The flexinference block

A stream that fails after it starts

Provider errors

Flex outcome headers

Handling errors in code