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.
Request and access errors
Section titled “Request and access errors”| HTTP | Code | Meaning and action |
|---|---|---|
| 400 | invalid_request | Check the JSON object, query type/length, and unsupported fields. |
| 400 | invalid_cursor | Restart workspace pagination; do not modify or reuse another account’s cursor. |
| 401 | unauthorized | Check the bearer header and key status. Also remove an Origin header, unexpected query parameters, or duplicate parameters. |
| 403 | premium_required | The account does not currently have eligible API access. Review Pro/trial status. |
| 403 | insufficient_scope | The credential does not have the required search:read scope. |
| 403 | cors_forbidden | CORS preflight is unsupported. Call from your server. |
| 404 | not_found | The workspace does not exist or is not owned by the account. List workspaces again. |
| 413 | body_limit | Send 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.
Rate and capacity errors
Section titled “Rate and capacity errors”All of these return 429 with Retry-After in seconds:
| Code | Meaning | Recovery |
|---|---|---|
ingress_rate_limit | Too many API requests from the client IP. | Slow all requests sharing that IP. |
metadata_rate_limit | Too many workspace-list requests for the account. | Cache workspace IDs and reduce list calls. |
search_start_limit | Too many API searches started in the current minute. | Queue requests and honor the delay. |
concurrent_search_limit | An API search is already active for the account. | Wait for it to finish or close it. |
service_capacity | Shared execution capacity is full. | Retry later with jitter. |
search_quota_exceeded | The account’s daily search allowance is exhausted. | Wait until the UTC reset or review allowance. |
Temporary service errors
Section titled “Temporary service errors”503 means the request could not safely proceed. Use bounded exponential backoff with jitter, and avoid automatic unbounded retries.
| Codes | Meaning |
|---|---|
api_disabled | Customer API execution is temporarily unavailable. |
authorization_unavailable | Current eligibility could not be verified. |
search_unavailable | Search execution or its response could not be completed. |
dependency_unavailable | A required dependency is unavailable. |
admission_unavailable, lease_unavailable | Search admission could not safely establish execution. |
rate_configuration_unavailable, rate_store_unavailable, rate_store_capacity, ip_attribution_unavailable | Request 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.
Stream errors and interruption
Section titled “Stream errors and interruption”An illustrative SSE terminal error:
event: errordata: {"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 messages
Section titled “Key-management messages”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.