Errors

The HTTP API uses standard status codes and a consistent error body. For the billing side of failures — and the rule that failed operations aren’t charged — see Errors & failures.

Error body

Every non-2xx response (other than 402) carries this JSON:

{
  "error": {
    "type": "input_error",
    "message": "The file at https://example.com/report.pdf could not be fetched (404).",
    "operation": "merge",
    "request_id": "req_8c1f…"
  }
}

• type — a stable machine-readable category (see below).
• message — a human-readable explanation; safe to surface to a developer.
• operation — which operation was attempted.
• request_id — include this when contacting support.

Status codes

Status	type	Meaning	Charged?
400 Bad Request	validation_error	Missing or invalid parameters.	No
400 Bad Request	input_error	A file couldn’t be fetched or isn’t a valid PDF.	No
400 Bad Request	payment_error	The X-PAYMENT payload was invalid, expired, or underfunded.	No
402 Payment Required	—	The payment challenge, not an error. Pay and retry.	—
422 Unprocessable Entity	processing_error	Well-formed request, but the document couldn’t be processed (e.g. wrong password, corrupt file, page range out of bounds).	No
429 Too Many Requests	rate_limited	Too many requests in a short window.	No
500 Internal Server Error	internal_error	A failure on our side.	Refunded if payment had settled
503 Service Unavailable	unavailable	Temporary capacity/maintenance.	No

Common cases

• Wrong password on remove password → 422 processing_error. Not charged.
• Unreachable input URL → 400 input_error. Not charged.
• Page range entirely out of bounds → 422 processing_error. Not charged. (Partial overlaps are clamped — see page ranges.)
• Bad or expired X-PAYMENT → 400 payment_error. Re-request to get a fresh 402 quote and pay again.

Rate limits

Because there are no accounts, the primary spam deterrent is payment itself — every call costs $0.05. On top of that, a per-wallet / per-IP request-rate limit protects the service from bursts. Exceeding it returns 429 with a Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 2

Back off (exponential backoff works well) and retry after the indicated delay.

Preview

Exact rate-limit thresholds are tuned during private preview and aren’t published yet. Normal agent workloads won’t hit them; if you have a high-throughput use case, mention it when you request access.

Retry guidance

Status	Retry?	How
400	No	Fix the request first; the message says what’s wrong.
402	Yes (automatic)	Your x402 client pays and retries.
422	No	Fix inputs (password, file, page range).
429	Yes	Honor Retry-After, back off.
500 / 503	Yes	Retry a few times; a settled payment is refunded if it ultimately fails.

Always keep the request_id for anything you escalate to support.