#The envelope
Every failure uses one envelope:
{ "error": { "code": "validation_failed", "message": "amount must be a positive integer", "details": {}, "request_id": "req_..." } }
request_id matches the x-request-id response header and the server log line. Branch on code, never on message.
#Common codes
The codes you will branch on most often: validation_failed, unauthorized, forbidden, not_found, conflict, idempotency_conflict, request_in_progress, provider_unavailable, provider_error, rate_limited, insufficient_funds, recipient_unverified, currency_unsupported, payload_too_large.
#Rate limits
Rate limiting answers 429 with retry-after and error.details.retry_after_seconds.