Error reference for every endpoint and tool

Every Flux error starts with an HTTP status, and most carry a machine-readable code. The abilities grew up one at a time, so today the code does not always sit in the same place: this page shows each shape, then lists every ability code in one table.

For chat and the money checks (every 402 refusal on a model call), see the chat error reference. This page covers the abilities and the two MCP servers, and links back there for chat.

Read the status first#

The tools server is the exception: it answers with HTTP 200 and puts the refusal inside the tool result. See Tools server results.

The error shapes#

Chat#

Chat and model calls use the OpenAI error shape. The code is at error.code, and 402 refusals carry their reason in a header or at error.provider_specific_fields.error, as the 402 section explains.

{"error": {"message": "Flux Router error: ...", "type": "invalid_request_error", "param": null, "code": "invalid_api_key"}}

Ability endpoints#

Speech to text, text to speech, the voice list, search, images and decision mode use the same outer shape. The code is at error.code, and param names the field at fault when there is one. Some 400s carry only param and no code.

{"error": {"message": "unsupported or unrecognized audio format", "type": "invalid_request_error", "code": "unsupported_file_format", "param": "file"}}

Images, when a credit check blocks the call#

The image endpoints wrap a balance or spend-cap refusal one level deeper, under detail. The code is one of the balance codes from the 402 section, such as credit_exhausted or daily_cap.

{"detail": {"error": {"code": "credit_exhausted", "message": "..."}}}

Page reading#

POST /v1/fetch returns a flat shape. The code is the error string itself, and message, when present, explains it.

{"error": "social_blocked", "message": "social-media mass-scrape is not supported"}

Tools server results #

The Flux tools server (/mcp-tools/) never answers a tool call with a protocol error. A refusal is a normal tool result whose structured content carries the code:

{
  "error": "rate_limited",
  "capability": "apps",
  "message": "Connected apps is busy for this account right now. Wait a moment, then retry.",
  "retryable": true,
  "retry_after_seconds": 30
}

• retryable tells your agent whether trying again can help.
• retry_after_seconds appears on some rate_limited answers.
• upgrade_url appears on premium_locked and payment_required.

Apps are reached only through the tools server, so every apps error arrives in this shape.

Routing server#

The routing server (/mcp) speaks JSON-RPC, so its errors are JSON-RPC errors with a numeric code:

{"jsonrpc": "2.0", "id": 1, "error": {"code": -32002, "message": "..."}}

Reading the code in one place#

This reads the code from any of the HTTP shapes above:

async function fluxErrorCode(res: Response): Promise<string | null> {
  const hold = res.headers.get('X-Flux-Hold-Reason');
  if (hold) return hold;
  const body = await res.json().catch(() => null);
  if (!body) return null;
  if (typeof body.error === 'string') return body.error; // page reading
  const err = body.error ?? body.detail?.error; // abilities, chat, image credit
  return err?.provider_specific_fields?.error ?? err?.code ?? null;
}

Every ability code#

Tools server codes#

Decision mode#

POST /v1/decide (and /v1/systemone) uses the ability-endpoint shape: the code is at error.code, and param names the request field at fault (model, state, questions, images or body), never a value. The message is fixed text: it never repeats your state, instructions, option text, question ids or images. Request details are on the decision mode reference.

Nothing is charged for any of these.

premium_locked, payment_required and credit_unresolved#

Three 402 codes look alike and need different fixes:

• premium_locked (or upgrade_required from page reading): your plan does not include paid abilities yet. Add a paid plan, or wait for your first payment to clear. Adding credit alone does not help.
• payment_required: a tool's route asked for payment. Usually the money ran out: your balance, or on apps the free daily runs, so add credit. The web_fetch tool also answers payment_required on a Free plan, where the fix is a paid plan, as for premium_locked.
• credit_unresolved: nothing is wrong with your account. Flux could not read your balance at that moment, so it refused rather than guess. Retry once; if it keeps happening, contact support.

Getting help#

Keep the X-Flux-Request-Id header from the failing response, or the time of a tool call, and contact support. That lets us find the exact request.