Reference
For the complete documentation index optimized for AI agents, see llms.txt.Current constraints and practical limits. These reflect the current implementation, not fundamental architectural boundaries.
Active-text mutation admission
The engine bounds foreground mutations that affect full-text indexes. These limits apply to Cloud and standalone HelixDB. Exceeding a bound rejects the write transaction before commit with HTTP 400 and codeactive_text_mutation_limit_exceeded; it does
not partially commit graph changes. The diagnostic reports the measured resource,
observed usage and configured limit.
The default entity ceiling is 512 distinct text-relevant graph entities per
collecting/flush epoch. Repeated changes to the same entity coalesce within an
epoch. Both nodes and edges can count when a text index observes their changes;
unrelated entities do not count. Consequently, the number of input IDs alone does
not establish whether a request fits. Internal text reads can flush an epoch, but
ordinary bulk deletes accumulate changes until their final text preparation.
Additional active-text defaults remain in force even below 512 entities:
Admission accounts for complete retained before/after property rows as well as text
index work. Large properties, multiple indexes, or tenant partitions can therefore
hit another bound with fewer entities. These are runtime policy limits, not storage
format maxima; embedded configurations can supply a different validated policy.
Reduce the number or size of mutations before retrying. If the application splits
one request into several, each new request is a separate atomic transaction. The
service does not automatically replay the rejected write. There is no time-based
Retry-After: waiting without changing the mutation does not resolve a hard limit.
See Error handling for the response
contract. HTTP 429 rate limiting below is a separate mechanism.
Helix Cloud request rate limits
Helix Cloud applies a distributed token bucket toPOST /v2/query. The bucket is
scoped to the authenticated Cloud database, so reads and writes from every API
key, application instance, and gateway replica draw from the same allowance.
Database-specific overrides can change the sustained rate, burst capacity, and query attempt budget.
The values assigned to your database take precedence over its plan limits. Each
admitted query request costs one token from one shared bucket per Cloud database.
Token-bucket behavior
- A full bucket can admit requests up to its burst capacity. Tokens then refill continuously at the plan’s sustained rate, up to that capacity. This is not a fixed one-second window.
- One incoming request consumes one token whether it is a read, write, or cache warming request. Warming fanout and gateway retries do not consume additional tokens.
- Requests rejected during authentication, gateway header validation, or outer request JSON decoding do not consume a token. Query AST and planner validation happen after admission, so those later validation failures consume one token.
- The bucket is shared across API keys and gateway replicas. Rotating keys or distributing calls across connections does not create more capacity.
- Burst capacity controls short-term admission, not the number of queries that can execute concurrently. Bound client concurrency separately.
Rate-limit responses
When no token is available, the gateway rejects the request before database execution:Retry-After is a whole number of seconds. Wait at least that long before
retrying, and add jitter when many workers share the same database. The response
does not currently include RateLimit-* or X-RateLimit-* limit, remaining, or
reset headers.
Current official SDK error objects expose the HTTP status, stable code, and
diagnostic, but not response headers. Use direct HTTP or an application
transport that retains headers when the exact Retry-After value is required;
otherwise use a configured, bounded status/code-aware delay with jitter.
If the gateway cannot make a safe distributed rate-limit decision, it fails
closed before database execution:
rate_limit_unavailable with bounded exponential backoff and jitter. A
402 tenant_disabled response is an account-credit gate, and a 408
query_timeout response is an execution deadline; neither means the request
bucket was exhausted.
Application guidance
- Coordinate admission across workers that target the same Cloud database.
- Honor
Retry-Afteronrate_limitedinstead of retrying immediately. - Use bounded exponential backoff with jitter for transient
503responses. - Bound in-flight concurrency as well as request rate to avoid local queues and latency spikes.
- Apply a separate per-user or per-workspace limiter when multiple application tenants share one Cloud database; the Helix bucket does not distinguish those application tenants.