56 lines (45 loc) · 2.88 KB

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 and POST /v1/crawl/screenshot 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.

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.
`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 is unavailable.
`504`	The backend service timed out.

Public Error Codes

Error Code	Meaning
`ACCOUNT_NOT_ACTIVE`	The account exists but is not allowed to execute requests.
`BROWSER_CONCURRENCY_LIMIT_REACHED`	The account has no remaining browser concurrency slots.
`DATABASE_NOT_CONFIGURED`	Public API storage is not configured.
`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.
`RATE_LIMIT_REACHED`	The account hit a per-minute request limit.
`RESERVATION_CONFLICT`	The gateway could not reserve internal capacity.
`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 crawl endpoint error bodies as the primary signal for automated retries.
Always log x-request-id for failed crawl calls.
Treat 400, 401, 402, and most 403 responses as non-retryable until you change input, credentials, or plan.
Treat 409, 429, 502, and 504 as candidates for backoff and retry.