Delivery Limits
Flux API enforces predictable ceilings so every delivery request stays fast and cacheable. These limits apply to all environments, regardless of subscription tier.
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. |
Flux API does not currently impose rate limits beyond these structural guards. Monitor usage dashboards if you need to track plan-level quotas.
Search & Query Limits
| Limit | Value | Behavior |
|---|---|---|
| Join folders | Up to 3 folders per _search | Additional joins return 422 too_many_join_folders. |
| 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_folders | 422 | _search.join references more than three folders. |
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.