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 caps on inputs and images 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-embed-2.0", "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.
`404`	Unknown model	The `model` id is not served. The `detail` string lists the available ids for that endpoint.
`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 cap: 256 inputs (embeddings, search) on the embedding models, 128 documents on `flinq-rerank-2.0`, or 16 images per request. Split the inputs across more requests. See Bulk & batch.
`422`	Input too long	A text exceeded the model’s per-input token limit (see Input length), or a query exceeded its limit. The `detail` string names the indices.
`422`	Unusable image	An image is not a base64 data URL (remote `http(s)` URLs are not fetched), is not PNG, JPEG or WebP, does not match its declared type, is over 5 MB or 50 megapixels, cannot be decoded, has a side under 4 px or an aspect ratio above 200:1. Also returned for an image sent to the text-only `flinq-embed-1.5-beta`, and for an image with `"input_type": "query"`.
`422`	Unsupported task	A `task` the model does not list in `GET /v1/models`. `flinq-embed-1.5-beta` takes no `task` at all.
`422`	Wrong model type	An embedding model sent to `/v1/rerank`, or the rerank model sent to `/v1/embeddings`, `/v1/search` or `/v1/chunk`. The `detail` string names the models for that endpoint.
`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.

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, and GET /v1/models reports it as max_batch:

Embedding models. 256 inputs per request on both flinq-embed-2.0 and flinq-embed-1.5-beta.
Rerank model. 128 documents per /v1/rerank request on flinq-rerank-2.0.

flinq-embed-2.0 and flinq-rerank-2.0 also accept at most 16 images per request (max_images). A request over a 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:

{
  "object": "list",
  "data": [
    {
      "id": "flinq-embed-2.0",
      "object": "model",
      "owned_by": "flinq",
      "type": "embedding",
      "stage": "ga",
      "max_input_tokens": 8192,
      "max_batch": 256,
      "max_query_tokens": null,
      "native_dim": 2048,
      "matryoshka_dims": [2048, 1024, 512, 256, 128],
      "modalities": ["text", "image"],
      "tasks": ["lv_matching", "image_search", "retrieval"],
      "max_images": 16,
      "max_image_bytes": 5000000,
      "image_max_pixels": 802816
    },
    {
      "id": "flinq-rerank-2.0",
      "object": "model",
      "owned_by": "flinq",
      "type": "rerank",
      "stage": "ga",
      "max_input_tokens": 3000,
      "max_batch": 128,
      "max_query_tokens": 1024,
      "native_dim": null,
      "matryoshka_dims": null,
      "modalities": ["text", "image"],
      "tasks": ["lv_matching", "image_search", "retrieval"],
      "max_images": 16,
      "max_image_bytes": 5000000,
      "image_max_pixels": 802816
    },
    {
      "id": "flinq-embed-1.5-beta",
      "object": "model",
      "owned_by": "flinq",
      "type": "embedding",
      "stage": "beta",
      "max_input_tokens": 8192,
      "max_batch": 256,
      "max_query_tokens": null,
      "native_dim": 1024,
      "matryoshka_dims": [1024, 768, 512, 256, 128],
      "modalities": ["text"],
      "tasks": [],
      "max_images": null,
      "max_image_bytes": null,
      "image_max_pixels": null
    }
  ]
}

On flinq-rerank-2.0, the query may have up to 1,024 tokens (max_query_tokens) and each document up to 3,000 tokens (max_input_tokens).

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.

Three 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.
Images are never truncated. An image is billed as its visual tokens (see Images) and does not count against the text token limit.

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.

Images

flinq-embed-2.0 accepts images on /v1/embeddings and flinq-rerank-2.0 on /v1/rerank, as OpenAI chat content parts with a base64 data URL. The limits, all reported by GET /v1/models:

PNG, JPEG or WebP only, inline as data:image/...;base64,.... Remote http(s) URLs are not fetched.
Up to 5 MB per image (max_image_bytes) and 50 megapixels before scaling; up to 16 images per request (max_images).
Each image is scaled down, keeping the aspect ratio, to at most 802,816 pixels (image_max_pixels, about 0.8 MP, for example 896 × 896). EXIF rotation is respected.
An image is billed as its visual tokens: one token per 32 × 32-pixel block after scaling, at most 784 tokens per image.

/v1/search is text-only. See Embeddings for examples.

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.