Flux RouterDocumentation

Web search problems

Fixes for Flux web search: free keys, 401 and 402 answers, empty answers and 502 codes, rate limits, and a chat request that did not search.

Each entry gives the symptom, the cause and the fix, keyed by the status and code in the error. The full contract is in the search reference; the guide is Search the web.

402 premium_locked

Symptom. POST /v1/search answers 402 with code: "premium_locked". From your agent, web_search answers premium_locked, then disappears from its tool list.

Cause. Search is a paid ability, and this key's plan is not paid and cleared yet. Nothing was charged.

Fix. Upgrade in Billing. See Plans. Restart your agent afterwards so it lists the tool again.

A Free key's chat request never searches

Symptom. A chat request with "tools": [{ "type": "web_search" }] on a Free key answers from the model's own knowledge, with no sources.

Cause. On Free keys the search tool is removed from chat requests, so the model answers without it. There is no error.

Fix. Upgrade in Billing, or call POST /v1/search from a paid key.

401 on /v1/search

Symptom. Search answers 401, while other calls with the same key may work.

Cause. The key is missing, mistyped, revoked or expired, or its model allowlist does not cover search.

Fix.

  • Send the key as Authorization: Bearer sk-flux..., in full.
  • Check the key on your keys page. If it has a model allowlist, try a key without one.
  • If a fresh key with no allowlist still gets 401, contact support.

402 credit_unresolved, or another 402 code

Cause. Your credit balance could not be checked (credit_unresolved), or your balance or a spend cap stopped the call. Nothing was charged.

Fix. Retry credit_unresolved after a short wait. For the others, add credit or raise the cap; see Spend caps.

502 with an empty answer

Symptom. Search answers 502 with one of these codes. None is charged.

codeCauseFix
upstream_emptyThe search found nothing to write an answer from.Reword the query: be specific, and name the thing you want.
upstream_error, upstream_incompleteThe search failed, or did not finish within 30 seconds.Retry. Split a broad question into narrower ones.
usage_unavailable, settlement_unavailableThe search ran but could not be priced or settled.Retry shortly.
capability_unavailableSearch is not available right now.Retry shortly.

400 on a request that looks right

Cause. query is empty or over 2,000 characters, or the body carries a field search does not take (model, tools or search_parameters).

Fix. Send {"query": "..."} and nothing else.

429 rate_limit_error

Cause. Search, transcription and speech share one per-account limit of 60 requests a minute.

Fix. Wait, then retry with backoff. See Rate limits and retries.

404, or the tool says ability_disabled

Cause. Search is not switched on for this account.

Fix. Do not retry. Contact support if you expected it to be on.

Symptom. A paid chat request answered without searching, and cited nothing.

Cause. Chat searches only on flux-auto, flux-fast, flux-standard and flux-reasoning, and only when the request carries a web search tool or the last message plainly asks for a search. A question about recent events, on its own, is not enough. A pinned model is always served as asked.

Fix. Do one of these:

  • Add "tools": [{ "type": "web_search" }] to the request.
  • Say it: "Search the web for ...".
  • Call POST /v1/search directly and pass the answer into your chat.

Still stuck

See the whole-API Errors page, or ask support.