Concepts
Errors, retries and limits
Every error code, which ones to retry, the rate limit, and how to retry without paying twice.
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.
{ "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 asurlrefused 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 sameIdempotency-Keyis still running. Retry after a few seconds.rate_limited(429): too many requests. Wait forRetry-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_unavailableandnot_configured(503): a Flux service is temporarily unavailable. Wait forRetry-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.