Skip to content

Errors and recovery

Before a stream opens, API errors use an HTTP status and a small JSON body:

{"error":"premium_required"}

After HTTP 200 opens a search stream, failures arrive as an SSE error event or an interrupted connection. Do not expect the HTTP status to change after headers have been sent.

HTTPCodeMeaning and action
400invalid_requestCheck the JSON object, query type/length, and unsupported fields.
400invalid_cursorRestart workspace pagination; do not modify or reuse another account’s cursor.
401unauthorizedCheck the bearer header and key status. Also remove an Origin header, unexpected query parameters, or duplicate parameters.
403premium_requiredThe account does not currently have eligible API access. Review Pro/trial status.
403insufficient_scopeThe credential does not have the required search:read scope.
403cors_forbiddenCORS preflight is unsupported. Call from your server.
404not_foundThe workspace does not exist or is not owned by the account. List workspaces again.
413body_limitSend a body at most 4,096 bytes and a known Content-Length.

A 401 response includes WWW-Authenticate: Bearer. An unmatched route or malformed UUID path can return a framework-level 404 rather than the JSON not_found contract. Proxies can also return non-JSON failures; check status and content type before decoding.

All of these return 429 with Retry-After in seconds:

CodeMeaningRecovery
ingress_rate_limitToo many API requests from the client IP.Slow all requests sharing that IP.
metadata_rate_limitToo many workspace-list requests for the account.Cache workspace IDs and reduce list calls.
search_start_limitToo many API searches started in the current minute.Queue requests and honor the delay.
concurrent_search_limitAn API search is already active for the account.Wait for it to finish or close it.
service_capacityShared execution capacity is full.Retry later with jitter.
search_quota_exceededThe account’s daily search allowance is exhausted.Wait until the UTC reset or review allowance.

503 means the request could not safely proceed. Use bounded exponential backoff with jitter, and avoid automatic unbounded retries.

CodesMeaning
api_disabledCustomer API execution is temporarily unavailable.
authorization_unavailableCurrent eligibility could not be verified.
search_unavailableSearch execution or its response could not be completed.
dependency_unavailableA required dependency is unavailable.
admission_unavailable, lease_unavailableSearch admission could not safely establish execution.
rate_configuration_unavailable, rate_store_unavailable, rate_store_capacity, ip_attribution_unavailableRequest protection could not safely admit the call.

Treat an unrecognized 5xx code as a temporary service failure. Preserve the status and error code for support; do not log the Authorization header or sensitive query/results.

An illustrative SSE terminal error:

event: error
data: {"code":"search_unavailable","partial":true,"count":3,"coverage":{"live_commit_history_included":false,"partial":true,"historical_snapshots":true,"current_head_complete":false,"deleted_or_superseded_content_may_be_present":true}}

Retain the three already-received hits and mark the run incomplete. A connection close without done or error is also incomplete. A retry starts from the beginning and can return duplicate hits or consume another search.

A done event with status: "paused" or status: "limited" is a bounded partial result, not the same as a protocol failure. Even status: "complete" must be interpreted alongside partial and corpus coverage.

Key management is performed in the application, outside the bearer API. The UI may report an active-key limit, an hourly creation limit, an unavailable issuance service, or a secret that can no longer be displayed. Revoke unused keys, wait for the creation window, or create a replacement for a lost secret. Do not automate the browser’s session-only management endpoints with API keys.