Error codes

All errors use standard HTTP status codes with a JSON detail body. The shape of detail varies by endpoint, but most authenticated endpoints use a structured object.

Error shape

{
  "detail": {
    "error": "unauthorized",
    "message": "Invalid API key or missing X-PAYMENT header"
  }
}

For scrape/extract failures, detail includes additional context:

{
  "detail": {
    "error": "timeout",
    "message": "Navigation timed out after 20000ms: https://slow.example.com",
    "url": "https://slow.example.com",
    "payment_charged": false
  }
}

Status codes

Code	Meaning	When it happens
`400`	Bad request	Invalid body, unknown `output`/`mode`, missing required fields, connection failures
`401`	Unauthorized	Invalid or missing API key / `X-PAYMENT` header
`402`	Payment required	x402 payment failed or insufficient (reserved for payment flows)
`404`	Not found	Unknown `job_id`, or a resource you don’t own
`429`	Rate limited	Per-IP or tier rate limit exceeded
`500`	Internal server error	Unexpected engine failure
`504`	Timeout	Navigation or fetch timed out

Structured `detail.error` values

The detail.error field is a machine-readable code you can branch on.

`detail.error`	Status	Endpoints	Meaning
`invalid_output`	400	scrape	`output` not in `markdown`/`screenshot`/`pdf`/`csv`/`html`
`invalid_mode`	400	crawl	Unknown crawl mode
`invalid_request`	400	extract, crawl	Missing required fields
`connection_failed`	400	scrape, extract	DNS/connection failure (incl. invalid host)
`unauthorized`	401	scrape, extract	Missing/invalid credentials
`rate_limited`	429	scrape, extract	Per-IP sliding window exceeded
`scrape_failed`	500	scrape	Unexpected engine failure
`extract_failed`	500	extract	Unexpected extraction failure
`webhook_delivery_failed`	502	webhooks/test	Test webhook delivery failed
`timeout`	504	scrape, extract	Navigation timed out

Retrying

429 rate limited — back off and retry. Check the Retry-After header if present, otherwise wait ~1s and retry with exponential backoff.
500/504 — safe to retry with exponential backoff. The scrape engine already retries internally up to 3 times before surfacing these.
400 — do not blindly retry; fix the request. The exception is connection_failed on a transient network error.
401 — fix authentication; retrying won’t help.

import time, httpx

def scrape_with_retry(url: str, headers: dict, attempts: int = 3):
    for i in range(attempts):
        resp = httpx.post(
            "https://api.tazpal.com/v1/scrape",
            headers=headers,
            json={"url": url},
        )
        if resp.status_code == 429 or resp.status_code >= 500:
            time.sleep(2 ** i)          # 1s, 2s, 4s
            continue
        resp.raise_for_status()
        return resp.json()
    raise RuntimeError("Max retries exceeded")

async function scrapeWithRetry(url, headers, attempts = 3) {
  for (let i = 0; i < attempts; i++) {
    const resp = await fetch("https://api.tazpal.com/v1/scrape", {
      method: "POST",
      headers,
      body: JSON.stringify({ url }),
    });
    if (resp.status === 429 || resp.status >= 500) {
      await new Promise((r) => setTimeout(r, 1000 * 2 ** i));
      continue;
    }
    if (!resp.ok) throw new Error(await resp.text());
    return resp.json();
  }
  throw new Error("Max retries exceeded");
}

Request IDs

Every response includes an X-Request-ID header. Pass your own X-Request-ID on the request to correlate logs, or read the server-generated one from the response.

curl -i https://api.tazpal.com/health
# HTTP/1.1 200 OK
# X-Request-ID: 3f9c1a2b-8d4e-4f6f-a0b7-5c3d9e1f2a4b