Rate limits and errors

This page covers how flinq authenticates requests and how it behaves at its edges: the error codes you can see, the per-key rate limit, the cap on inputs per request, and what happens when your credit balance runs out.

Every request authenticates with a Bearer API key, issued in the console and shaped like flq_.... Put it in the Authorization header:

curl https://api.flinq.ai/v1/embeddings \
  -H "Authorization: Bearer flq_..." \
  -H "Content-Type: application/json" \
  -d '{ "model": "flinq-pilot-otter", "input": "Beton C25/30 XC4" }'

Usage draws down your prepaid EUR credit balance. When the balance reaches zero, the API stops with a hard stop rather than running up a surprise bill. See Pricing for the pay-as-you-go rate and credit packs.

Errors

The API returns FastAPI-style JSON. On any error the body is a single object with a detail string:

{ "detail": "insufficient credit — add credit in the flinq console" }

Status	Meaning	What to do
401	Invalid or missing key	Check the Authorization: Bearer ... header and that the key is active in the console.
401	Revoked key	The detail string says the key has been revoked. Create a new key in the console.
402	Insufficient credit balance	The detail is "insufficient credit — add credit in the flinq console". Top up in the console; the next request goes through immediately.
402	Monthly spending limit reached	The detail is "monthly spending limit reached — raise it in the flinq console or wait for next month". Raise the cap, or wait for the calendar month to roll over.
413	File too large	A /v1/extract or /v1/chunk upload exceeded the 20 MB cap.
422	Too many inputs	A request exceeded the serving model’s input cap (2048 for flinq-pilot-otter, 256 for flinq-pilot-wombat). Split the inputs across more requests. See Bulk & batch.
422	Unusable file	A /v1/extract or /v1/chunk upload is not well-formed XML or not a GAEB file, or a chunking parameter is invalid. The detail string names the problem.
429	Rate limited	A per-key limit was exceeded: requests per minute, billable tokens per minute, or concurrent requests in flight. The detail string names which. Back off and retry after the Retry-After header; the OpenAI SDK does this for you.

The 402 hard stop

A 402 is a hard stop, not a bill: requests stop rather than rolling into a surprise invoice. Top up your balance, or raise the monthly cap, to resume.

A 401 covers both an absent key and one that does not match; a revoked key gets its own detail string so the two cases are distinguishable. Note that GET /v1/models is deliberately public (a discovery endpoint that never bills), so a working /v1/models call says nothing about whether your key is valid. A 429 is transient and safe to retry after the Retry-After interval.

Inputs per request

The cap on inputs per request is per model. A request over the cap returns 422 rather than silently truncating. To embed a larger corpus, chunk below the cap and run a few requests concurrently; the Bulk & batch page has a ready recipe and notes the asynchronous batch endpoint on the roadmap.

Input length and truncation

Each model also has a per-input token limit. Query it programmatically — GET /v1/models is the source of truth:

{ "id": "flinq-pilot-wombat", "max_input_tokens": 8192, "max_batch": 256, ... }

By default, an input over the limit returns 422 with the offending indices in the detail string. Nothing is ever truncated silently. If you prefer truncation over an error, opt in per request with "truncation": "auto": each over-limit input is cut at the limit, the affected indices come back in the response’s truncated field, and a human-readable note lands in warnings.

Two rules hold in every mode:

• Billing never exceeds what the model consumed. Tokens past a model’s input limit are never billed, in any mode, on any endpoint.
• Queries are never truncated. On /v1/search and /v1/rerank, an over-limit query is always a 422 — a silently cut query would change what is being searched for.

On /v1/chunk with a model, chunks that exceed the model’s input limit (for example with max_chunk_size_tokens above the limit) are billed at most the limit and flagged in warnings.

/v1/rerank bills the query once per request plus the document tokens, matching the compute actually delivered.

Document uploads

The document endpoints (/v1/extract, /v1/chunk) accept one file per request, up to 20 MB, and return 413 above the cap.

Parsing is deliberately tolerant: the parser auto-detects GAEB DA XML 3.2 and 3.3, and content it does not recognize is preserved as unparsed raw text with an entry in the response’s warnings array rather than failing the request. A hard 422 occurs only for files that are not well-formed XML or whose root element is not <GAEB>.

Supported today: GAEB DA XML only. PDF ingestion, including scanned documents, is not supported yet; it is on the roadmap as a layout-aware release together with OCR.

Rate limits

Rate limits are per key, enforced as a requests-per-minute (RPM) ceiling. When you exceed it the API returns 429 with a Retry-After header telling you how long to wait before the next attempt.

When you hit a 429, honor Retry-After and retry with exponential backoff: wait the indicated interval, then double it on each subsequent failure, with a little random jitter so many clients do not retry in lockstep. If you use the OpenAI SDK pointed at flinq, this is automatic; the SDK retries 429 responses with backoff out of the box, so most callers need to write no retry logic at all.

The 402 hard stop

Usage is metered against your prepaid EUR credit balance. When the balance reaches zero, the API returns 402 on the next billable request and stops serving until you top up. This is deliberate: the limit is a stop, not a bill, so you never get a surprise invoice.

To resume, top up your balance in the console. The credit lands right away, and the next request goes through. Credit does not expire, so anything left over carries forward.

An optional monthly spending cap works the same way from the other side. If you set a euro ceiling for the calendar month, the API returns 402 once that ceiling is reached, even with credit still on your balance. Raise the cap in the console to resume immediately, or wait for the month to roll over. The cap is off by default; the opt-in auto-recharge option can instead top the balance up automatically so long runs do not stall at zero. See Pricing.