Errors and limits

Error envelope

All 4xx/5xx responses share one shape:

{
  "error": {
    "type": "rate_limit",        // see ErrorType below
    "message": "Rate limit exceeded",
    "request_id": "8f1c2e7a-…",  // uuid — quote this in support requests
    "retryable": true
  }
}

type is one of: timeout, auth, rate_limit, http, parse, unavailable, invalid_request.

Status codes

Status	`type`	When	Retryable
`401`	`auth`	Missing, malformed, unknown, inactive, or revoked API key.	No
`402`	`invalid_request`	Billing block. The `message` distinguishes the cause (below).	After resolving billing
`403`	`invalid_request`	Account inactive.	No
`422`	—	Invalid request body (validation).	No
`429`	`rate_limit`	Rate limit or concurrency cap exceeded. Honors `Retry-After`.	Yes, after backoff
`500`	`unavailable`	Internal error.	Yes
`200` + `degraded:true`	—	Partial results — one engine failed but another returned. Not an error.	—

If all eligible engines fail with no successful failover, the request returns an error envelope rather than partial results.

402 billing causes

The 402 message carries the specific reason:

insufficient_credit — prepaid balance exhausted (and auto top-up didn't cover it). Add credits.
no_free_managed — a free account tried to run a managed (platform-key) search. Managed requires a paid tier. Use BYOK or upgrade.
managed_requires_billing — managed search with no billing on file. Add a payment method or credits.
byok_no_key — a BYOK search but no valid provider key for the chosen engine. Add the engine key.
free_cap_exceeded — the free tier's monthly routed-search cap (250,000) was reached.
spend hard-stop — a configured spend cap was hit.

Rate, burst, and concurrency limits

Limits are per plan. The token bucket is keyed per API key (rate + burst); concurrency is capped per tenant. A 429 includes a Retry-After header (seconds).

Plan	Rate (req/s)	Burst	Max concurrency
Free	2	5	3
BYOK	30	60	30
Managed	50	100	50
Enterprise	100	200	100

When you exceed the per-second rate (after consuming the burst allowance) you get 429 with Retry-After. When you have more in-flight requests than your concurrency cap, additional requests get 429 until one completes.

Free-tier quota

The free (BYOK) tier is capped at 250,000 routed searches per month. Past the cap, searches return 402 free_cap_exceeded. Upgrade to a paid tier to lift the cap.

Handling errors

Always read request_id from the envelope (or the X-Request-Id header) and quote it in support requests.
On 429, back off for Retry-After seconds before retrying.
On 402, inspect the message — most causes are resolved by adding credits, adding a provider key, or upgrading the plan.
degraded: true on a 200 means you have usable (partial) results — handle them, optionally retrying for completeness.

PreviousPricing