Errores

Los errores usan el código HTTP adecuado y un cuerpo con un código estable para que tu código decida qué hacer:

JSON

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

Cada respuesta trae X-Request-Id; mencionalo si contactás a soporte.

HTTP	Código	Significado
400	invalid_parameter	Parámetro de query inválido (ver fields).
400	invalid_json	El cuerpo no es un objeto JSON.
400	credentials_in_url	Pusiste un valor de seguridad en la URL.
400	invalid_idempotency_key	Idempotency-Key con formato inválido.
401	missing_credentials / invalid_credentials	Faltan cabeceras o tienen formato inválido.
401	timestamp_out_of_range	Reloj desfasado más de 5 minutos.
401	invalid_signature	Firma incorrecta o clave inexistente/regenerada.
401	replayed_request	Nonce repetido.
403	ip_not_allowed	IP fuera de la lista permitida.
403	merchant_disabled	Cuenta no habilitada.
404	not_found · module_not_found · payment_not_found	No existe o es de otro comercio.
405	method_not_allowed	Método HTTP incorrecto (ver cabecera Allow).
409	module_unavailable	Módulo, sitio o cuenta deshabilitados (en producción el sitio tiene que estar verificado).
409	payment_not_refundable · refund_already_requested	El pago no admite devolución o ya tiene una.
413	body_too_large	Cuerpo mayor a 64 KB.
415	unsupported_media_type	Content-Type incorrecto.
422	validation_failed	Revisá error.fields.
422	method_unavailable · no_methods_available	Método no disponible para ese módulo, monto o país.
422	idempotency_key_reused	Misma Idempotency-Key con otro cuerpo.
429	rate_limited	Límite de llamadas; esperá Retry-After segundos.
500	internal_error	Error nuestro: reintentá y, si sigue, escribinos con el request_id.
503	service_unavailable	Mantenimiento o API desactivada; reintentá después de Retry-After.

Reintentá solo los 429, 500 y 503 (con espera). Para crear pagos o devoluciones, reintentá con la misma Idempotency-Key.