Skip to content

errors-and-headers.md

Latest commit

 

History

History
76 lines (61 loc) · 5.68 KB

errors-and-headers.md

File metadata and controls

76 lines (61 loc) · 5.68 KB
Raw

Errors and Headers

This page describes the status codes, error codes, and response headers used by the public API.

Header Availability

  • POST /v1/crawl/page, POST /v1/crawl/screenshot, and POST /v1/search return gateway metadata headers on both success and error responses.
  • GET /v1/account/usage does not guarantee gateway metadata headers. SDK meta fields for that endpoint may therefore be null except for status.

Response Headers

Header Meaning
x-request-id Unique gateway request identifier. Include this value when you contact support or investigate logs.
x-credits-reserved Credits reserved before request execution.
x-credits-used Credits actually settled after execution.
x-browser-ms-used Browser execution milliseconds reported by the backend, or 0 when browser timing does not apply.
x-analytics-as-of Optional timestamp for a complete fixed-cut analytics snapshot. This describes statistics freshness, not the age of the current credit balance. Exact eventual reads do not claim this snapshot watermark.
x-analytics-freshness Optional degraded marker for a lagging snapshot or temporarily incomplete eventual statistics.
x-analytics-consistency Optional eventual marker for exact reads of asynchronously delivered request states.
x-analytics-pending-since Optional enqueue time of the oldest pending latest request revision affecting an eventual read. It is not the request's original completion date.
Retry-After Minimum delay before retrying a temporary availability response, when provided.

HTTP Status Codes

Status Meaning
200 Request succeeded.
400 The JSON body or a field value is invalid.
401 The API key is missing, invalid, or revoked.
402 The account does not have enough credits to reserve the request.
403 The account is not active, or the current plan does not allow the requested field override.
409 The gateway could not reserve internal capacity. Retry the request.
413 The request body exceeds the 256 KiB public gateway limit, or fetched content/output exceeds the configured processing safety limit.
429 The account hit a rate limit or browser concurrency limit.
502 The gateway could not connect to the backend service.
503 A required backend configuration or a usable analytics snapshot is unavailable.
504 The shared request execution budget expired, including body reading, pagination and provider fallback.

Public Error Codes

Error Code Meaning
ACCOUNT_NOT_ACTIVE The account exists but is not allowed to execute requests.
ANALYTICS_UNAVAILABLE Account statistics are temporarily being prepared. Honor Retry-After; the response does not represent a zero usage total.
BROWSER_CONCURRENCY_LIMIT_REACHED The account has no remaining browser concurrency slots.
DATABASE_NOT_CONFIGURED Public API storage is not configured.
CONTENT_TOO_LARGE The target content, DOM, screenshot or generated output exceeds a configured processing safety bound. Reduce the requested content or screenshot scope before retrying.
INSUFFICIENT_CREDITS There are not enough credits to reserve the request.
INVALID_API_KEY The API key is missing, invalid, or revoked.
INVALID_REQUEST The request body or one of the request fields is invalid.
PAID_PLAN_REQUIRED The request uses a field that is only available on paid plans.
PAYLOAD_TOO_LARGE The request body exceeds the public gateway size limit.
RATE_LIMIT_REACHED The account hit a per-minute request limit.
RESERVATION_CONFLICT The gateway could not reserve internal capacity.
SEARCH_PROVIDER_NOT_CONFIGURED The search provider is not configured.
UPSTREAM_BAD_RESPONSE The search provider returned an unexpected response.
UPSTREAM_CONNECTION_FAILED The gateway could not reach the backend service.
UPSTREAM_TIMEOUT The backend service did not respond before timeout.
WORKER_NOT_CONFIGURED A required backend service is not configured.

Retry Guidance

  • Use retryable=true in gateway error bodies as the primary signal for automated retries.
  • Always log x-request-id for failed crawl, screenshot, and search calls.
  • Treat 400, 401, 402, 403, and 413 responses as non-retryable until you change input, credentials, plan, or request size.
  • Treat 409, 429, 502, and 504 as candidates for backoff and retry.
  • For 503 ANALYTICS_UNAVAILABLE, honor Retry-After. Configuration errors need operator action rather than an unlimited retry loop.

Execution and Delivery

Pagination, provider-key fallback and response-body reading share one execution budget; each step does not receive a new full timeout. Existing prices and actual-result billing remain unchanged. A request that observes cancellation or expiry before choosing a successful financial outcome does not settle as success.

A connection can still break after the financial transaction commits. A missing client response alone does not prove that no credits were settled. Preserve x-request-id and inspect its log before blindly repeating an expensive request; the client-supplied correlation ID is not an idempotency key.

Analytics freshness headers and temporary availability responses apply when the migrated analytics reader is enabled. Exact eventual reads with an existing usable baseline can temporarily return degraded, incomplete statistics; a missing baseline or delivery lag of five minutes returns 503. Fixed-cut snapshots retain their as-of watermark. A genuinely empty account can still return zero usage. The successful JSON structure is unchanged.