Errors

Payzor returns JSON errors with an HTTP status code:

{ "error": "Saldo insuficiente. Disponible: $56 USDC" }

Status codes

Status	Meaning	Typical cause
`400`	Bad request	Missing/invalid field (`amountUsdCents` not a positive integer, bad address…).
`401`	Unauthenticated	Missing or wrong credential; the message names the expected one.
`402`	Payment required / policy rejected	Budget exceeded, per-charge cap, or the agent’s hard limits blocked the payment. The body explains exactly why.
`403`	Forbidden	Valid credential, wrong scope (e.g. another merchant’s resource), or KYT-blocked address.
`404`	Not found	Unknown charge/PayLink/endpoint id.
`409`	Conflict	Operation invalid for current state (paying a paid charge, expired PayLink).
`500`	Server error	Bug or infrastructure issue. Safe to retry.
`503`	Service unavailable	Feature requires PostgreSQL and it isn’t configured; x402 facilitator unreachable.

Policy rejections are 200s (sometimes)

One nuance worth knowing: when an agent pays a charge and its policy blocks or pauses the payment, the endpoint still answers 200 with a structured outcome rather than an error code:

{ "paid": true, "charge": { "...": "..." } }                        // settled
{ "pendingApproval": true, "approvalId": "...", "reason": "..." }   // paused for human
{ "error": "Categoría 'services' no está ..." }                     // blocked (HTTP 402)

Agents are programs that branch on outcomes; giving them a machine-readable reason is more useful than a bare status code.

Designing your integration around errors

Branch on the three payment outcomes, not just success/failure.
Parse budget errors: excede_presupuesto_restante_350 embeds the exact remaining cents.
Retry on 5xx only. 4xx means your input or state is wrong; repeating won’t help.
Log reference values from successful payments; they match across merchant charges and agent audit trails.

​Errors

​Status codes

​Policy rejections are 200s (sometimes)

​Designing your integration around errors

Errors

Status codes

Policy rejections are 200s (sometimes)

Designing your integration around errors