Limits
Limits an integrator can run into. Server-side derivation tuning is not listed — it is not something you can set or observe.
Rate limits
Section titled “Rate limits”| Limit | On breach | |
|---|---|---|
| Per-IP, token endpoint | 10/min | 429 + Retry-After |
| Global | 600/min | 429 + Retry-After |
Both fail closed: when the limiter cannot make a decision, the request is refused rather than allowed through.
Retry-After is in whole seconds and the SDK waits it rather than applying its own backoff — the
server knows when the bucket refills, the client does not. Exhausted retries surface a typed
RateLimitedError carrying it.
A 429 from the token endpoint uses the RFC 6749 OAuth shape, not our fault envelope, and puts
its correlation id only in X-Request-Id. The SDKs normalise both into one typed error.
Payload
Section titled “Payload”| Limit | On breach | |
|---|---|---|
| Request body | see payload_too_large | 413 |
Not retryable. Shrink the batch or use the presigned payload_ref flow. An SDK that retried a
413 would send the same too-large body again.
Batches
Section titled “Batches”evidence.ingest takes a batch and can partly succeed — 200 with accepted[] and rejected[],
which is a success with a mixed result, not a failure.
Do not retry the whole batch; resubmit the rejected subset. See Write evidence back.
Timeouts
Section titled “Timeouts”| Default | Whose | |
|---|---|---|
| Per-attempt | 30s | client |
| Total | 60s | client |
latency_budget_ms | 800ms | server, on context.assemble |
The first two are client-side and fail the call. The third is server-side and degrades — returning a smaller answer, not an error. Do not conflate them: a degraded assemble is a success and must not consume a retry. See Degraded mode.
Your own context deadline always wins. Backoff sleeps consume the total budget.
Retrieval
Section titled “Retrieval”| Note | |
|---|---|
top_k | Defaults to 8. Raising it costs tokens and latency; measure with context.report before assuming more is better |
| Graph expansion | One hop. Multi-hop traversal does not exist |
Scope lattice
Section titled “Scope lattice”Only exact match and org:* are structurally computable. Everything else fails closed. See
Scopes and inheritance.
Retry policy
Section titled “Retry policy”| Outcome | Retried |
|---|---|
| Transport error before a response | yes |
429 | yes, after Retry-After |
500, 503 | yes, with backoff |
400, 401, 403, 404, 409, 410, 413 | no |
| Any verdict, any decision | no — a success |
422 is never emitted. Anything not listed is not retried, because an unknown status is an
unknown cause.