Flux logo
Flux
Docs
Concepts

Concepts

Errors, retries and limits

Every error code, which ones to retry, the rate limit, and how to retry without paying twice.

2 min read · Updated 20 Nov 2026
On this page

An error has an HTTP status and a JSON body with a stable code, a message written for a person, and the request_id. Branch on code, not on the message. A request that returns an error is not charged.

A real 401, for a wrong key
{  "error": {    "code": "unauthorized",    "message": "Missing or invalid API key.",    "request_id": "req_d17ed00b6ae0465c9b759544"  }}

Error codes

  • bad_request (400): the request is malformed, or a page given as url refused to be read. The message says what to change. Do not retry unchanged.
  • unauthorized (401): the key is missing, wrong or revoked.
  • insufficient_credits (402): the balance is used up. Add credit, then retry.
  • not_found (404): the resource, such as a batch handle, does not exist.
  • idempotency_in_progress (409): a request with the same Idempotency-Key is still running. Retry after a few seconds.
  • rate_limited (429): too many requests. Wait for Retry-After, then retry.
  • fetch_failed (502): Flux could not read the page you asked for, usually because the site blocks automated access. Try another source.
  • upstream_error (502): a problem on the Flux side. Retry with backoff.
  • search_unavailable, pricing_unavailable and not_configured (503): a Flux service is temporarily unavailable. Wait for Retry-After, then retry.

Rate limit

The default limit is 60 requests a minute. Over it, you get 429 rate_limited with a Retry-After header in seconds. The same code is used when Flux is briefly overloaded, with a short Retry-After. Either way, wait that long before retrying. GET /account and GET /models are not rate limited.

Retrying without paying twice

A request can time out on your side after Flux has done the work. Send an Idempotency-Key header with POST /lineage, /search, /fetch or /batch, and reuse it when you retry. Flux runs the request once:

  • A repeat with the same key and the same body returns the stored response, with Idempotency-Replayed: true, and is not charged again.
  • A repeat while the first is still running returns 409 idempotency_in_progress.
  • The same key with a different body is a 400. Use a new key for each new request.
  • Keys are 8 to 255 characters of letters, digits and _ : . -, and are remembered for 24 hours. A UUID works well.

This retries the statuses worth retrying, waiting as told, with one key for every attempt:

import osimport timeimport uuidimport requestsRETRY = {409, 429, 502, 503}def flux_post(path: str, body: dict, attempts: int = 4) -> dict:    headers = {        "Authorization": f"Bearer {os.environ['FLUX_API_KEY']}",        "Idempotency-Key": str(uuid.uuid4()),  # the same key on every attempt    }    for attempt in range(attempts):        response = requests.post(f"https://fluxsearch.io/api/v1{path}", json=body, headers=headers, timeout=120)        if response.ok:            return response.json()        if response.status_code not in RETRY or attempt == attempts - 1:            error = response.json()["error"]            raise RuntimeError(f"{error['code']}: {error['message']} ({error.get('request_id')})")        time.sleep(int(response.headers.get("Retry-After", 2 ** attempt)))if __name__ == "__main__":    result = flux_post("/search", {"query": "UK inflation latest figure", "enrich": 0})    print(result["results"][0]["url"])
const RETRY = new Set([409, 429, 502, 503]);async function fluxPost(path: string, body: unknown, attempts = 4) {  const headers = {    Authorization: `Bearer ${process.env.FLUX_API_KEY}`,    "Content-Type": "application/json",    "Idempotency-Key": crypto.randomUUID(), // the same key on every attempt  };  for (let attempt = 0; ; attempt++) {    const response = await fetch(`https://fluxsearch.io/api/v1${path}`, {      method: "POST",      headers,      body: JSON.stringify(body),    });    if (response.ok) return response.json();    if (!RETRY.has(response.status) || attempt === attempts - 1) {      const { error } = await response.json();      throw new Error(`${error.code}: ${error.message} (${error.request_id})`);    }    const wait = Number(response.headers.get("Retry-After") ?? 2 ** attempt);    await new Promise((resolve) => setTimeout(resolve, wait * 1000));  }}const result = await fluxPost("/search", { query: "UK inflation latest figure", enrich: 0 });console.log(result.results[0].url);

Request IDs

Lineage, search, fetch and the OpenAI-compatible endpoints return an X-Request-Id header. Lineage, search and fetch also return it in the body as request_id, including on errors. Send your own X-Request-Id, up to 64 letters, digits, underscores or hyphens, to have it echoed back, which helps match Flux requests to your own logs. Quote it when you contact support.

Next steps