Error reference

FluxRouter returns standard HTTP status codes with an OpenAI-compatible JSON error body. Use this page to map a code to a cause and a fix.

Quick reference#

Every error body follows the OpenAI error shape:

{
  "error": {
    "message": "Incorrect API key provided.",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

The Anthropic-compatible endpoint returns the Anthropic error shape instead, with a top-level type of error and an error object inside it. The status codes and meanings below apply to both.

Full status reference#

Read the message field for the specific reason. The most common cases:

Why am I getting a 401?#

Symptom: Every request fails with 401 and an authentication error message.

Cause: The key is missing, malformed, or not a Flux key. This includes a leftover OpenAI or Anthropic key, a typo, or a missing Authorization header.

Fix:

• Send your Flux key, which starts with sk-, as a bearer token:

  bashCopy

  curl https://api.fluxrouter.ai/v1/chat/completions \
    -H "Authorization: Bearer sk-..." \
    -H "Content-Type: application/json" \
    -d '{"model":"flux-auto","messages":[{"role":"user","content":"ping"}]}'
  

• On the Anthropic path you can use x-api-key: sk-... instead.

• Confirm there is no trailing whitespace or quote characters around the key.

• If you rotated the key, update it everywhere your client reads it (environment variable, config file, secrets store).

402 refusals #

An HTTP 402 (Payment Required) means the request was refused on a money check rather than served. It is a safety limit, not a bug, and it is recoverable. Lowering max_tokens or switching models will not clear it.

Every money refusal is HTTP 402 with a machine-readable code. Branch on the code, not on the message text, which may be reworded.

Where the code is#

FluxRouter has two money gates and, today, they carry the code in two different places. A client that parses only one fails silently on the other.

Balance and caps example: status 402, header X-Flux-Hold-Reason: credit_exhausted, body:

{"error":{"message":"Your credit balance is exhausted. Top up to keep going. Top up at https://fluxrouter.ai/home/billing","type":"None","param":"None","code":"402"}}

Here code is the string "402": it restates the status. The reason is in the header.

Account gates example: status 402, no X-Flux-Hold-Reason header, body:

{"error":{"message":"account_monthly_budget_exhausted","type":"None","param":"None","code":"402","provider_specific_fields":{"error":"account_monthly_budget_exhausted","account_max_budget_usd":0.01,"spent_usd_this_month":0.0,"inflight_usd":0.1,"message":"This account's $0.01 monthly cap is exhausted. Upgrade your plan or wait until the next billing cycle.","upgrade_url":"https://fluxrouter.ai/home/billing"}}}

Read the header first and fall back to the body. This works for both families:

async function callFlux(body) {
  const res = await fetch('https://api.fluxrouter.ai/v1/chat/completions', { /* ... */ });
  if (res.status !== 402) return res;

  const payload = await res.json();
  const code =
    res.headers.get('X-Flux-Hold-Reason') ??
    payload?.error?.provider_specific_fields?.error ??
    null;

  switch (code) {
    case 'credit_exhausted':                   return topUpBalance();
    case 'daily_cap':                          return waitUntilUtcMidnight();
    case 'monthly_cap':                        return raiseMonthlyCapOrWait();
    case 'account_monthly_budget_exhausted':   return requestHigherCeiling();
    case 'free_tier_exhausted':                return addAPaidPlan();
    case 'credit_unresolved':                  return retryThenContactSupport();
    default:                                   return surfaceToOperator(code, payload);
  }
}

Every refusal code#

Four of these look alike and need four different fixes. An exhausted balance needs money. A reached daily cap needs time or a higher cap. A reached monthly cap needs a higher cap or the next month. A reached account ceiling needs a ceiling increase: a top-up will not clear it.

The same table, machine-readable. This block is the published contract: a test fails if it and the set of codes the gateway can emit ever differ. measured: true marks the refusals driven against the live API and captured on the wire; the rest come from the gateway's own refusal sites.

{"refusal_codes": [
  {"code": "credit_exhausted",                 "http_status": 402, "family": "credit", "carrier": "header", "measured": true},
  {"code": "credit_unresolved",                "http_status": 402, "family": "credit", "carrier": "header", "measured": true},
  {"code": "daily_cap",                        "http_status": 402, "family": "credit", "carrier": "header", "measured": true},
  {"code": "monthly_cap",                      "http_status": 402, "family": "credit", "carrier": "header", "measured": true},
  {"code": "account_monthly_budget_exhausted", "http_status": 402, "family": "gate",   "carrier": "body",   "measured": true},
  {"code": "spend_ceiling_unresolved",         "http_status": 402, "family": "gate",   "carrier": "body",   "measured": false},
  {"code": "free_tier_exhausted",              "http_status": 402, "family": "gate",   "carrier": "body",   "measured": false},
  {"code": "premium_locked",                   "http_status": 402, "family": "gate",   "carrier": "body",   "measured": false},
  {"code": "tier_locked",                      "http_status": 402, "family": "gate",   "carrier": "body",   "measured": false},
  {"code": "key_lifetime_cap_exhausted",       "http_status": 402, "family": "gate",   "carrier": "body",   "measured": false},
  {"code": "account_disputed",                 "http_status": 402, "family": "gate",   "carrier": "body",   "measured": false},
  {"code": "byok_no_capable_provider",         "http_status": 402, "family": "gate",   "carrier": "body",   "measured": false},
  {"code": "byok_no_deployment",               "http_status": 402, "family": "gate",   "carrier": "body",   "measured": false},
  {"code": "byok_no_account",                  "http_status": 402, "family": "gate",   "carrier": "body",   "measured": false},
  {"code": "byok_no_key",                      "http_status": 402, "family": "gate",   "carrier": "body",   "measured": false}
]}

Requests already in flight at the cutoff#

There is always a short gap between the moment a limit is reached and the moment the last request already in flight settles, so a client running many requests at once can end up slightly past the line. Any overshoot past your balance is ours. It is never carried forward, it never appears on a later invoice, and it never reduces a later top-up.

Fixing a 402#

Monthly caps and ceilings reset each calendar month; daily caps reset at midnight UTC.

Why am I getting a 429?#

Symptom: Bursts of requests fail with 429.

Cause: You are sending requests faster than your plan allows, or, on the Free plan, the monthly token allowance is used up. The second case carries "state": "free_cap_reached" in the error body and does not clear with a retry.

Fix:

• Back off and retry. Use exponential backoff (for example 1s, 2s, 4s) with jitter, and honour Retry-After.
• Reduce concurrency, or add a small delay between requests in tight loops.
• For free_cap_reached, move to a paid plan or wait for the next month. See The Free plan.
• See Rate limits and retries for patterns.

Why am I getting a 5xx?#

Symptom: Occasional 500, 502, 503 or 504 responses.

Cause: A transient upstream model error or a gateway hiccup.

Fix:

• Retry the request with backoff. Most 5xx responses are transient and succeed on retry.
• If a specific request fails repeatedly, capture the X-Flux-Request-Id from the response and contact support with that id.
• Persistent 5xx on every request usually points to a malformed request body. Check that your JSON is valid and that messages (or input) is well formed.

Ability errors#

This page covers chat and model calls. The abilities (speech, transcription, images, search, page reading, apps) and the two MCP servers use a few other error shapes and codes:

• Error reference for every endpoint and tool: every shape and every ability code, with whether to retry.
• Fixes for each ability:
  • Speech to text problems
  • Text to speech problems
  • Image problems
  • Web search problems
  • Read a page problems
  • Second opinion did not run
  • App problems
  • Tools server problems

Including the request id#

For any error you escalate, include the X-Flux-Request-Id response header and email support at fluxrouter dot ai. The id lets support find your exact request. See Receipts for how to read response headers.