Errors
Every error is a status code with a plain-language reason. Nothing internal is ever returned in an error body.
Status codes
400 — a malformed query or an invalid filter value. The response names the parameter. 401 — "missing api key" or "invalid api key"; the two are distinguished so you can tell configuration from credentials. 402 — quota exhausted on a hard-capped plan. 403 — the account is suspended. 429 — rate limit exceeded; back off and retry. 408 — the query exceeded the server timeout, which defaults to 10 seconds. 503 — the node is up but the index is not loaded; retry.
What errors never contain
Storage-layer errors are never passed through to a response body. Those messages can carry bucket names and credential-adjacent detail, so they are logged internally and the caller receives a generic failure. If you are debugging something that looks like an infrastructure error, the status code is all there is — and that is intentional.
Retrying
Retry 429, 408 and 503 with exponential backoff. Do not retry 400, 401 or 403 — they will not succeed on a second attempt. 402 resolves at the start of the next billing period, or by upgrading.
Health and readiness
/healthz reports liveness and /readyz reports whether the index is actually loaded and non-empty. During a deploy those differ: a node can be up and answering health checks while still loading, which is why readiness refuses traffic until there is an index to serve from.
Start on the free tier
10,000 requests a month, no card. Everything documented here works on every plan.