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:

Plan	Requests per minute
Free	120
Starter	600
Pro	1,200
Enterprise	custom

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.

Billing — retrieval allowances, rate limits per plan, and the 402 plan_exhausted behavior when a Free-tier allowance is exhausted.
Flux API errors — the full delivery error contract.
Management API limits — structural plan quotas for authoring.