Errors

Errors are JSON with a single human-readable field: { "error": "…" }. The cases:

402 Payment Required

Not an error so much as the front door — but it also serves as the “try again” response:

• No payment attached — the normal first response; terms are in the payment-required header.
• Payment didn’t verify — bad signature, wrong amount, expired quote, or a quote for a different option. Nothing was charged (a payment that doesn’t verify never settles). Read the fresh terms and sign again.
• Balance exhausted — on prepaid endpoints: the re-fund quote. Your session token stays valid; pay the top-up and continue.

See The 402 response for the full shape.

404 Not Found

{ "error": "unknown gateway route" }

The path doesn’t match a live endpoint — check the seller’s catalog (Discovering sellers). You’ll also get this for the wrong HTTP method on an existing endpoint (endpoints are registered per method).

Origin failures — you don’t pay

If the seller’s origin fails after your payment was accepted for processing, settlement doesn’t happen — the money settles only after the response is delivered:

• On a per-call payment, a failed delivery means no settle.
• On a prepaid draw, the draw is automatically re-credited to your balance.

And if a payment did settle but the response never reached you (connection dropped at the worst moment), re-send the same signed payment header shortly after: it acts as a one-time receipt and the gateway re-serves the delivery without charging again (GET endpoints). A background reconciler backstops every remaining edge, so a settled payment is never silently lost.

503 Service Unavailable (tolled sites)

{ "error": "agent toll temporarily unavailable" }

Rare, on toll-mode domains only: the toll can’t be quoted right now, and agents are asked to retry (Retry-After is set) rather than being let in free — the seller asked for a toll, so the wall never silently waives it. Human visitors are unaffected.

Rate limits

The gateway applies sensible per-seller rate limiting to keep any one buyer from starving an endpoint. If you’re building a high-volume integration against a specific seller, prepaid credit (one settle, then off-chain draws) is both the fastest and the most limit-friendly path.