Errors and request ids

Every error has an HTTP status that fits and the same JSON body. Check code in your code: it is stable. message is for people and may change.

{  "error": {    "code": "not_found",    "message": "session not found",    "requestId": "req_4fJx0aQm2Lk9Pz7N"  }}

Request ids

Every response, not only errors, has an X-Request-Id header: the API’s own id for the request (req_…). Errors repeat it as error.requestId. The same id is in the API’s log line for a failed request, so quote it when you ask for support.

To tie a request to your own logs, send your own id in X-Client-Request-Id (or X-Request-Id): 1 to 64 letters, digits, ., _, : or -. It comes back in the X-Client-Request-Id response header and is logged next to the API’s id. Anything else is ignored. Your id never replaces the API’s own.

In the SDKs, pass your id as clientRequestId (Python: client_request_id in options). Their errors carry both ids, and the typed error classes let you handle one case, such as RateLimitError or NotFoundError.

curl -i https://api.boxline.dev/v1/sessions/does-not-exist \  -H "x-api-key: $BOXLINE_API_KEY" \  -H "X-Client-Request-Id: checkout-worker-42"# HTTP/1.1 404 Not Found# x-request-id: req_4fJx0aQm2Lk9Pz7N# x-client-request-id: checkout-worker-42# {"error":{"code":"not_found","message":"…","requestId":"req_4fJx0aQm2Lk9Pz7N"}}

import { Boxline, BoxlineError } from "@boxline/sdk";const bx = new Boxline();try {  await bx.sessions.get("does-not-exist", { clientRequestId: "checkout-worker-42" });} catch (err) {  if (err instanceof BoxlineError) {    console.log(err.status, err.code, err.message); // 404 not_found …    console.log(err.requestId, err.clientRequestId); // req_4fJx0aQm2Lk9Pz7N checkout-worker-42  }}

from boxline import Boxline, BoxlineErrorbx = Boxline()try:    bx.sessions.get("does-not-exist", options={"client_request_id": "checkout-worker-42"})except BoxlineError as err:    print(err.status, err.code, err.message)  # 404 not_found …    print(err.request_id, err.client_request_id)  # req_4fJx0aQm2Lk9Pz7N checkout-worker-42

Error codes

The codes you are most likely to meet, and whether trying again can help:

captcha_timeout comes in the action’s result (ok: false, code: "captcha_timeout"), not as an HTTP error. The SDKs raise it with status 409, and their waitForHuman / wait_for_human raise the same code with status 408 when their own wait runs out. An agent run or task run that was accepted and then failed carries its own errorCode instead, such as output_invalid (see Structured output) or not_started (see Tasks). Each API reference page lists the errors of its endpoint.

Why a page did not load

A page that cannot be loaded gives 502 page_unreachable. The message names the host and Chrome’s reason, for example could not load example.com: ERR_NAME_NOT_RESOLVED. For some connection problems Chrome only says that the tunnel failed (ERR_TUNNEL_CONNECTION_FAILED). The session machine’s own proxy knows why, so the message adds it in words:

could not load status.example.invalid: ERR_TUNNEL_CONNECTION_FAILED (the name does not resolve (DNS))

The same words are in the error of a failed goto action in a session (page.goto: net::ERR_TUNNEL_CONNECTION_FAILED at https://status.example.invalid/ (the name does not resolve (DNS)), which stays ok: false; the SDKs’ one-action methods raise it as action_failed), and for fetch, screenshot, PDF, extract and crawl, where the status stays 502. When the machine cannot say, the message is Chrome’s own.

Retrying well

• Retry only what can succeed later: 429, 503, 502 from a machine, and network errors.
• Wait longer each time (1 s, 2 s, 4 s…), with some randomness, and give up after a few tries.
• On 429, wait at least the Retry-After seconds.
• Send an Idempotency-Key on calls that create something, so a retry never creates it twice.
• Never retry project_suspended, feature_not_in_plan, spend_limit, out_of_credit, role_forbidden or email_unconfirmed: they will not change by themselves. A person has to change a plan, a limit, a role or confirm an email.
• The SDKs follow these rules for you: they retry GETs and creates with an idempotency key, and never other POSTs. See the Node SDK and the Python SDK.