Error reference (401, 402, 429, 5xx)

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/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 (env var, config file, secrets store).

Why am I getting a 402?#

Symptom: Requests fail with 402 after previously working.

Cause: Your account hit a spend ceiling. On the Free plan this is a hard $1 cap. On paid plans it is your account ceiling.

Fix:

• If you are on Free, you have reached the $1 cap. Add a payment method or upgrade to keep going.
• If you are on a paid plan, raise your account ceiling or add funds in the dashboard.
• A 402 is not a routing or model problem. Lowering max_tokens or switching models will not clear it; the cap is per account.

Why am I getting a 429?#

Symptom: Bursts of requests fail with 429.

Cause: You are sending requests faster than the allowed rate.

Fix:

• Back off and retry. Use exponential backoff (for example 1s, 2s, 4s) with jitter.
• Reduce concurrency, or add a small delay between requests in tight loops.
• A single retry after a short pause clears most transient 429s.

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. Validate your JSON and that messages (or input) is well formed.

Including the request id#

For any error you escalate, include the X-Flux-Request-Id response header. It lets support locate your exact request. See Find out which model answered for how to read response headers.