Troubleshooting

Something not working? Most problems fall into a handful of buckets, and almost all of them clear after four quick checks.

What to check first#

1. The base URL matches the protocol. OpenAI-compatible tools use https://api.fluxrouter.ai/v1. Anthropic-compatible tools, such as Claude Code, use https://api.fluxrouter.ai/anthropic with no /v1. There is no bare /chat path.
2. The key is your Flux key. It starts with sk-. Send it as Authorization: Bearer sk-... (the Anthropic path also accepts x-api-key: sk-...). A leftover OpenAI or Anthropic key returns 401.
3. The model is real. Use flux-auto or another flux-* id. See Models.
4. Keep the X-Flux-Request-Id. Every response carries one. Include it when you ask for help so support can find your exact request.

Pages in this section#

• My agent won't connect: wrong base URL, wrong key, rejected model id, and per-agent gotchas.
• Error reference: what each status code means, including every 402 refusal code.
• Latency and timeouts: slow responses and client-side timeouts.
• Truncated or empty output: responses that stop early or come back blank.

Abilities#

• Speech to text problems: file size, formats, and keys that are not allowed the model.
• Text to speech problems: voices, formats and speeds that do not suit the model, and saving the audio.
• Image problems: edits, reference images, max_price and moderation.
• Web search problems: free keys, empty answers, and chat that did not search.
• Read a page problems: social networks, private addresses and rendering.
• Second opinion did not run: tool turns and agent loops are skipped.
• App problems: sign-in links, pending connections, free runs, second accounts and unknown actions.
• Tools server problems: the trailing slash, the key header, and tools that are locked or missing.

Every ability error code is in the error reference for every endpoint and tool.

To see which model answered a request and what it cost, read Receipts.

Still stuck?#

Grab the X-Flux-Request-Id from the failing response, note the base URL and model id you used, and email support at fluxrouter dot ai. Those three details resolve most questions on the first reply.