Delivery Limits
Flux API enforces predictable ceilings so every delivery request stays fast and cacheable. Most of these limits are structural and apply to all environments regardless of tier; the request rate limit scales with your subscription plan.
Request Execution
| Limit | Value | How it is enforced |
|---|---|---|
Results per request (limit) | 1 to 100 | Values above 100 are clamped; values below 1 return 422 invalid_request. |
| Response payload size | ~1 MiB | Responses larger than ~1 MiB (after population and formatting) return 413 max_response_size_exceeded. |
| Request timeout | 60 seconds | Requests exceeding 60 seconds return 408 request_timeout. |
| Secure timestamp window | ±15 minutes | Secure signatures with Date headers outside this window return 401 authentication_required. |
Rate Limiting
The Flux API applies a per-organization request rate limit that scales with your plan. The values for each plan are on the Pricing page.
When you exceed the rate limit, Flux returns HTTP 429 with error_code: rate_limited and a Retry-After header giving the number of seconds to wait before retrying.
HTTP 429 — rate limit exceeded
{
"error_code": "rate_limited",
"message": "Rate limit exceeded"
}
Rate-limited (429) responses are free — they are never billed as retrievals. Retry with backoff after the interval in Retry-After.
Rate limiting is separate from your monthly retrieval allowance. If a Free-tier organization exhausts its retrieval allowance for the billing window, Flux reads return HTTP 402 with error_code: plan_exhausted instead of 429. See Billing for retrieval allowances, overage, and the full metering contract.
Search & Query Limits
| Limit | Value | Behavior |
|---|---|---|
| Join collections | Up to 3 collections per _search | Additional joins return 422 too_many_join_collections. |
| Population depth | 3 levels | populate paths deeper than three levels are ignored. |
| Full-text query length | 1,000 characters | find_text/find_phrase queries are truncated to 1,000 characters. |
| Vector query length | 1,000 characters | vector_search.query is truncated to 1,000 characters; top_k and boost counts max out at 100 results. |
| Text search exclusivity | 1 per request | Only one of find_text or find_phrase can be present. |
| Vector configuration | Required when using vector/hybrid modes | Omitting vector_search when search_mode is vector, vector_boosted, or hybrid returns 422 invalid_request. |
Pagination & Cursor Rules
| Rule | Description |
|---|---|
| Cursor exclusivity | next and previous query parameters are mutually exclusive. If both are provided, Flux returns 422 invalid_request. |
| Cursor validity | Flux returns absolute next/previous URLs. You may follow them directly or reuse the embedded cursor token. |
| Cursor lifetime | A cursor remains valid until the referenced resource is deleted. Deleting a resource invalidates cursors that point to it, resulting in 404 responses when re-used. |
See the Pagination guide for end-to-end examples.
Limit Error Codes
Flux surfaces descriptive error codes whenever a delivery request hits one of the limits above. Handle them just like other Flux error responses.
| Error code | Status | When it occurs |
|---|---|---|
request_timeout | 408 | Request exceeded the 60-second timeout window. Retry with backoff. |
max_response_size_exceeded | 413 | Response would exceed the ~1 MiB limit. Reduce limit, projections, or populate. |
too_many_join_collections | 422 | _search.join references more than three collections. |
invalid_request | 422 | General validation failure (e.g., limit < 1, both cursors provided, missing vector_search). |
authentication_required | 401 | Secure signature too old/too far in the future or malformed. |
If an error persists, inspect the request payload, reduce the requested data size, or split synchronization jobs into smaller batches. Contact support if you need higher technical limits.
Related
- Billing — retrieval allowances, rate limits per plan, and the
402 plan_exhaustedbehavior when a Free-tier allowance is exhausted. - Flux API errors — the full delivery error contract.
- Management API limits — structural plan quotas for authoring.