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 balance. Top up to continue." }

Status	Meaning	What to do
401	Invalid or missing key	Check the Authorization: Bearer ... header and that the key is active in the console.
402	Insufficient credit balance	Your EUR balance is empty. Top up in the console; the next request goes through immediately.
402	Monthly spending limit reached	You set an optional monthly cap and it has been reached. 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	The per-key RPM limit was exceeded. Back off and retry after the Retry-After header. The OpenAI SDK does this for you.

A 402 carries one of two detail strings so you can tell the cases apart: "Insufficient credit balance. Top up to continue." when the balance is empty, and "Monthly spending limit reached. Raise the cap or wait for the next month." when an optional cap has been hit.

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 429 is transient and safe to retry after the Retry-After interval.

Inputs per request

The cap on inputs per request is per model: 2048 for flinq-pilot-otter (matching the OpenAI layout) and 256 for flinq-pilot-wombat. 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.

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.