Errors & failures

Things go wrong: a URL won’t fetch, a password is incorrect, a file isn’t a valid PDF. This page explains how those are reported and — importantly — how they affect billing.

Failed operations aren’t charged

The agent-trust default

If an operation fails, you should not pay for it. When a request fails before payment, no payment is requested. When a failure is detected after payment (rare — e.g. processing fails on an already-paid request), the charge is refunded. The intent is simple: you pay for results, not attempts.

The precise refund mechanics for post-payment failures are being finalized during preview; the operating principle — don’t charge for failures — is fixed. See the FAQ for the current status.

Error categories

Category	When it happens	Charged?
Validation error	Missing/invalid parameters, unsupported value	No — fails before payment
Input error	URL unreachable, file not a PDF, file too large	No
Password error	Wrong password on remove password	No
Payment error	Invalid/expired X-PAYMENT, insufficient funds	No — payment didn’t settle
Processing error	A valid, paid request that fails during processing	Refunded
Rate limited	Too many requests in a short window	No

HTTP error shape

On the HTTP API, errors use standard status codes and a consistent JSON body:

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

Status	Meaning
400 Bad Request	Validation or input error — check error.message.
402 Payment Required	Not an error — the payment challenge. Pay and retry.
422 Unprocessable Entity	The request was well-formed but the document couldn’t be processed (e.g. wrong password, corrupt PDF).
429 Too Many Requests	Rate limited — back off and retry.
500 Internal Server Error	Processing failure on our side — safe to retry; a settled payment is refunded.

Always include the request_id when contacting support — it lets us find the exact request.

For the full HTTP status reference see HTTP API → Errors.

Errors over MCP

When a tool call fails, the MCP server returns a tool error with the same type and message fields, so your agent can read what went wrong and decide whether to retry, fix inputs, or give up. As with HTTP, a failed tool call is not charged.

Retry guidance

• 400 / 422 — don’t blind-retry; fix the input first (the message says what’s wrong).
• 402 — expected once per call; your x402 client pays and retries automatically.
• 429 — back off (exponential is fine) and retry.
• 500 — retry a couple of times; if it persists, contact support with the request_id.