Errors

Errors use the proper HTTP status and a body with a stable code so your code can decide what to do:

JSON

{"error":{"code":"validation_failed","message":"Revisá los campos marcados.","fields":{"amount":"Obligatorio…"},"request_id":"8384c031057ccd7c"}}

Every response carries X-Request-Id; quote it if you contact support.

HTTP	Code	Meaning
400	invalid_parameter	Invalid query parameter (see fields).
400	invalid_json	The body is not a JSON object.
400	credentials_in_url	You put a security value in the URL.
400	invalid_idempotency_key	Malformed Idempotency-Key.
401	missing_credentials / invalid_credentials	Missing or malformed headers.
401	timestamp_out_of_range	Clock off by more than 5 minutes.
401	invalid_signature	Wrong signature or nonexistent/regenerated key.
401	replayed_request	Repeated nonce.
403	ip_not_allowed	IP not on the allowlist.
403	merchant_disabled	Account not enabled.
404	not_found · module_not_found · payment_not_found	Does not exist or belongs to another merchant.
405	method_not_allowed	Wrong HTTP method (see Allow header).
409	module_unavailable	Module, site or account disabled (in production the site must be verified).
409	payment_not_refundable · refund_already_requested	The payment cannot be refunded or already has a refund.
413	body_too_large	Body larger than 64 KB.
415	unsupported_media_type	Wrong Content-Type.
422	validation_failed	Check error.fields.
422	method_unavailable · no_methods_available	Method not available for that module, amount or country.
422	idempotency_key_reused	Same Idempotency-Key with another body.
429	rate_limited	Rate limit; wait Retry-After seconds.
500	internal_error	Our error: retry and, if it persists, write to us with the request_id.
503	service_unavailable	Maintenance or API disabled; retry after Retry-After.

Only retry 429, 500 and 503 (with backoff). When creating payments or refunds, retry with the same Idempotency-Key.