Errors

{
  "error": {
    "code": "insufficient_credits",
    "message": "This request needs 5 credits; 3 are left this month."
  }
}

Match on error.code, not the message; messages may change. Some codes add fields next to code and message (below). Every error response also carries x-request-id, x-credits-used: 0 and x-credits-remaining; every 429 carries Retry-After.

All codes

A POST body that is not a JSON object (for example sent as text/plain) gets 415 invalid_request; invalid JSON gets 400 invalid_request. Codes may be added over time; treat an unknown code by its HTTP status.

Why a request was refused (402)

A 402 (insufficient_credits or spend_limit_reached) always says why in error.reason and where to fix it in error.billing_url, your Billing page. credits_needed (what the request costs) and credits_remaining are added when known. Nothing is charged, and retrying does not help until the reason is fixed.

{
  "error": {
    "code": "insufficient_credits",
    "message": "This request needs 5 credits; 3 are left this month.",
    "reason": "free_credits_used",
    "billing_url": "https://pageteer.vercel.app/app/billing",
    "credits_needed": 5,
    "credits_remaining": 3
  }
}

New reasons may be added: treat an unknown one like the code it comes with, and send the user to billing_url. Crawls and batches that stop for credits keep the insufficient_credits: … or spend_limit_reached: … prefix in their error and may carry the same reason.

Extra fields

{
  "error": {
    "code": "invalid_request",
    "message": "Unknown field \"foo\" (see /openapi.json for the accepted fields)",
    "issues": [{ "path": "", "message": "Unknown field \"foo\" (see /openapi.json for the accepted fields)" }]
  }
}

{
  "error": {
    "code": "target_rate_limited",
    "message": "The target asked us to slow down, so we are pausing requests to it. Retry after 120 s. You were not charged.",
    "retry_after": 120,
    "reason": "retry_after",
    "target_status": 503
  }
}

DNS errors

A domain that does not exist is 400 invalid_request ("Could not resolve host X: the domain has no DNS record. Check the URL."): fix the URL. A temporary DNS failure (resolver timeout, SERVFAIL) is 502 internal_error with retryable: true ("DNS lookup for X failed temporarily (…). Retry shortly. You were not charged."): retry it. Batches retry such URLs for you.

Retrying

• Retry 429 after Retry-After seconds, and 500/502/504 with exponential backoff and jitter (for example 1 s, 2 s, 4 s, at most 3 or 4 tries). See Rate limits for a loop.
• Do not retry unchanged: 400, 401, 403, 404, 409, 413 and 422, nor proxy_failed with reason auth or blocked. They fail the same way again. 402 needs the reason fixed first.
• Retrying a POST /v1/crawl or POST /v1/batch after a 5xx or a network error could start a second job, unless you send an Idempotency-Key: then retries are safe.

What is charged

Only successful responses are charged. When the target answers, that is a success even if its status is a 3xx or 4xx: a 200 from us with "status": 404 in the body is charged, because we did the work. A site that answers 5xx is not charged, and every error in the table above is free, including timeouts, blocked targets, CAPTCHAs and our own failures. See Credits.

target_blocked

The body carries block_reason, block_vendor (cloudflare, akamai, datadome, …, or generic; null when unknown) and attempts. block_reason tells you what to try next:

• empty_response: the page had no visible text (often a JavaScript page). Retry with mode: "browser" if you used http.
• status_403, status_429, challenge_page, block_page (the page says you were blocked): a stronger unblock tier may help; if auto already tried them all, give up or retry much later.

captcha_required

Pageteer does not solve CAPTCHAs. When a request meets one, on any tier, it stops and returns this error (a JavaScript check that clears by itself in a browser is first waited out once, as described in Unblocking), with provider set to the CAPTCHA (recaptcha_v2, hcaptcha, turnstile) or the bot-protection vendor (for example cloudflare) when we can tell, else null.

{
  "error": {
    "code": "captcha_required",
    "message": "The target answered with a CAPTCHA or bot challenge (cloudflare). Pageteer does not solve CAPTCHAs, so we stopped without trying other tiers. You were not charged.",
    "provider": "cloudflare",
    "block_reason": "challenge_page",
    "status": 403,
    "attempts": [{ "tier": "none", "status": 403, "ms": 412, "blocked": true, "block_reason": "challenge_page", "captcha": true }]
  }
}

proxy_not_configured and proxy_failed

unblock: "residential" goes through your team's own proxy. Without one saved in Settings → Proxy you get 403 proxy_not_configured (and 404 from POST /v1/proxy/test). When the proxy itself fails you get 502 proxy_failed with a reason: auth (it rejected the credentials), unreachable, status (it refused to connect to the site) or blocked (its host resolves to a private address). Neither is charged. auth and blocked fail the same way until you fix the URL; the others may pass on retry. See Bring your own proxy.

{
  "error": {
    "code": "proxy_failed",
    "message": "Your team proxy rejected its credentials (HTTP 407). Check the username and password in your proxy settings. You were not charged.",
    "reason": "auth",
    "proxy_status": 407,
    "retryable": false
  }
}

Batch outcomes

In a batch, each URL that fails ends with one of these codes as its outcome (and in error.code), instead of an HTTP error. Batches also use ok for a fetched page, target_error when the site kept answering 5xx and canceled when the batch was canceled first. Crawl pages record the code in error. New codes may be added: treat unknown ones as a failure for that URL. Failed and canceled URLs are never charged.