Develop / Reference
Limits
Which size, time and quantity limits the gateway checks itself and how it handles the providers' rate limits.
This page lists only the limits the gateway enforces itself. The providers have their own, often tighter limits, for example for a model’s context length or image size. The provider reports such errors, and the gateway passes its message on under the code provider_rejected_request, see Error codes.
Body size
| Endpoints | Maximum body | Error when exceeded |
|---|---|---|
/v1/files and /v1/skills with sub-paths | 600 MB | 413 request_too_large |
all other endpoints under /v1/ | 160 MB | 413 request_too_large |
MB here means 1024 × 1024 bytes. The limits count the bytes that actually arrive, including for a body without Content-Length. They deliberately lie above any regular request. Tighter limits for individual endpoints are listed further down.
Waiting for the provider
| Limit | Value | Error when exceeded |
|---|---|---|
| Connecting to the provider | 10 seconds | 504 provider_timeout |
| Waiting for data from the provider | 120 seconds | 504 provider_timeout |
| Providers per request (failover) | at most three | error after the attempt at the last provider |
| Waiting for a free provider | 10 seconds | 503 capacity_exhausted |
If the time runs out at a provider, the gateway tries the model’s next provider, if there is one. Only if the last provider does not answer do you receive provider_timeout. The gateway does not follow redirects (3xx) from the provider; it returns them unchanged.
A failover switches only between providers of the same kind: never from your own provider key (BYOK) to a provider managed by Noirdoc, and never the other way round. More on this under Providers & routing. Capacity explains when the gateway waits for a free provider.
Rate limits
After the first confirmed top-up (or when billed by invoice, or on routes with your own provider), the gateway sets no rate limits per customer or key. While a new organisation is still using only its starter credit, only starter-eligible models can be called on providers managed by Noirdoc (the gateway rejects other managed models beforehand with 403 starter_model_not_allowed), and the gateway limits requests to managed providers to 5 requests per minute and 25 requests per day (UTC) across the organisation (429 starter_rate_limit_exceeded with Retry-After). Requests rejected by the minute limit or starter_model_not_allowed do not count towards the daily limit. The first confirmed top-up unlocks all managed models and lifts both limits immediately, see Credit & billing.
Independently of this, the gateway limits a provider to the concurrent requests and the requests per time window that Noirdoc has set for it, and routes around a full provider. If all providers of a model are full, it waits up to 10 seconds and then answers with 503 capacity_exhausted and Retry-After. If the gateway’s own connection pool to the providers is exhausted, it answers with 503 forwarding_pool_exhausted and Retry-After: 5. If a provider reports a capacity problem or an overload (status code 429, 402, 503 or 529), the gateway tries the model’s next provider. If there is no other, you receive 429 resource_exhausted or provider_overloaded (503, or 529 on /v1/messages and /v1/skills), each with the Retry-After header. It states the wait time in seconds, see Error codes. The gateway does not pass on other provider headers, such as x-ratelimit-*.
Budgets and credit limit the costs, not the number of requests. They lead to status code 402, see Budgets per key and Credit & billing.
Image generation
/v1/images/generations checks before forwarding:
| Parameter | Limit |
|---|---|
prompt | non-empty string |
n | whole number from 1 to 10, default 1 |
size | WIDTHxHEIGHT, each side 1 to 2048 pixels; 1024x1024 if not given; "auto" is not allowed |
| Megapixels per request | at most 16 |
Megapixels count per image, rounded up (1024x1024 = 1, 1536x1024 = 2, 2048x2048 = 4), times n. For example, ten images in 1024x1024 come to 10 and are allowed. Five images in 2048x2048 come to 20, and the gateway rejects the request. Split such requests into several. The gateway answers violations with 400 invalid_image_request. More under Images.
Rerank
/v1/rerank checks before forwarding:
| Field | Limit |
|---|---|
query | non-empty string |
documents | list of 1 to 1,000 strings |
top_n | not given, or a whole number from 1 |
The endpoint accepts no images or other content parts. The gateway answers violations with 400 invalid_rerank_request. More under Rerank.
Audio
| Endpoint | Limit | Error |
|---|---|---|
/v1/audio/transcriptions | body at most 26 MB (26 × 1024 × 1024 bytes), including all form fields | 413 request_too_large |
/v1/audio/speech | input at most 4,096 characters, voice required | 400 invalid_tts_request |
More under Audio.
Noirdoc Shield
For Noirdoc Shield and the endpoints under /v1/shield, the gateway enforces these limits:
| Limit | Value | Error when exceeded |
|---|---|---|
| Text to inspect per gateway request | at most 4 MiB of encoded text | 413 shield_input_too_large |
| Inline UTF-8 text attachments in requests | under 4 MiB decoded | 422 shield_uninspectable_content (enforced) |
input on POST /v1/shield/inspect | 1 to 64 non-empty strings, at most 256 KB UTF-8 in total | 400 invalid_request_error |
Custom blocklist (custom_patterns) | up to 100 patterns, 2 to 256 characters each (re: regex or case-insensitive literal) | 400 invalid_request_error |
Inline files of 4 MiB or above decoded, as well as binary documents (such as PDF or Office), images, audio and file references, cannot be inspected as text by Shield. Without enforced, Shield inspects the remaining text of the request and sets X-Noirdoc-Shield: partial; redacted=<n> (X-Noirdoc-Masked: false); under enforced, the gateway rejects the request with 422 shield_uninspectable_content.
Files in requests
Sending files, images and audio requires admins of your organisation to turn on Allow file and image attachments in requests under Models → Shield (Advanced Settings; otherwise 403 file_content_not_allowed). Under Noirdoc Shield, inline UTF-8 text attachments under 4 MiB decoded are inspected directly (see Files and images and Files).
On pre-existing organisations still using legacy file analysis until 30.11.2026, the Maximum file size setting applies (default: 25 MB per file). In the legacy file-analysis modes pseudonymize and block, the gateway rejects files that are too large, in any format, with 422 file_unprocessable instead of forwarding them unchecked.
For files you upload through /v1/files, only the 600 MB body limit applies; below it, the provider’s limits apply, see Files & Skills.
Request tags (Preview)
When the Request tags Preview feature is enabled for your organisation, the gateway enforces the following limits on the X-Noirdoc-Tags header and /v1/tags:
| Limit | Value | Error when exceeded |
|---|---|---|
Tags per request in X-Noirdoc-Tags | 1 to 5 comma-separated names | 400 invalid_request_tags |
| Tag name length and format | 1 to 64 characters (^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,63}$, not _default) | 400 invalid_request_tags |
| Tags per organisation | at most 1,000 | 403 tag_limit_exceeded |