Flux logo
Flux
Docs
Reference

Reference

Troubleshooting

Symptoms you might see, what causes them, and what to do.

2 min read · Updated 20 Nov 2026
On this page

Each section starts from what you see. When you contact support, include the request_id from the response or the error body. It identifies the request in our logs.

Every request returns 401

unauthorized: the key is missing, mistyped or revoked.

  • Send it as Authorization: Bearer $FLUX_API_KEY. A key in any other header is ignored.
  • Check the variable is set in the shell that runs your code: echo "${FLUX_API_KEY:0:5}" prints the first five characters.
  • If the key was revoked, create a new one on the API keys page.
Response
{  "error": {    "code": "unauthorized",    "message": "Missing or invalid API key.",    "request_id": "req_d17ed00b6ae0465c9b759544"  }}

A search result has lineage: null

enrichment tells you why. skipped means it was past your enrich count or the page could not be read. pending means it was still being read when the search returned.

  • Raise enrich to read more results. The price of a search does not change.
  • For pending, ask again.
  • For a page that cannot be read, send its URL to Lineage on its own. You get the site's reason in the error.

enriched_text is the same as text

Nothing in the passage needed filling in, and enrichment is none. This is not an error.

  • Send enriched_text anyway. It is never null.

A date has the wrong year

A partial date such as May 12 takes its year from the page's date, marked (year inferred). Your own text has no date unless you give it one, so the year can come from another date in the text.

  • Set published to the text's publication date, as an ISO date.
  • Check year_inferred on the annotation before you treat the year as stated.

A search returns fewer results than max_results

max_results is how many results are asked for. The index can answer with fewer, and the count is not guaranteed.

  • Broaden the query, or run a second search with different wording.

A filtered search returns results: []

No page on the allowed domains matched. The query in the response shows what was searched, with your domains added as site: operators.

  • Check the domains are spelled as they appear in URLs, without https://.
  • Widen the query, or add domains.
Response
{  "request_id": "req_2a37a0854c664f1b90465294",  "status": "completed",  "query": "sodium-ion battery energy storage site:example.com",  "results": [],  "filters": {    "allowed_domains": [      "example.com"    ],    "blocked_domains": []  },  "answer": null,  "related_queries": [],  "usage": {    "searches": 1,    "results_returned": 0,    "results_enriched": 0,    "cost_usd": "0.0040000000",    "cost_usd_ticks": 40000000  }}

Lineage returns 400 for a URL

The site refused the request or the page does not exist. The message gives the reason, such as The page returned HTTP 404. Nothing is charged.

  • Open the URL in a browser to confirm it exists.
  • In a documents request, one bad page does not fail the rest. It is listed in errors.

Lineage requests time out

A long page, or several questions over many documents, can take a minute or more.

  • Set a client timeout of at least 120 seconds.
  • For hundreds of documents, use POST /batch and collect the results when they are ready.

402 insufficient_credits

The workspace balance is used up.

  • Add credit on the billing page, then retry the same request.

Next steps