Errores y fallos

Hay dos cosas distintas y conviene no mezclarlas:

• Un error de la API (4xx/5xx): el pedido no se pudo atender. Llega siempre en el mismo sobre: {"error": {"code", "message", "details"}}. Compare code, muestre message. details sólo viene en los errores de validación, con un ítem por campo.
• Un fallo de la operación (status: failed): el pedido se atendió, la operación existe, y no salió. failure.code dice por qué y es un valor cerrado, fijo, para decidir; failure.reason es el motivo normalizado debajo del código, para explicar; failure.message es un texto legible que depende del motivo. Nunca traen el código crudo del banco ni del proveedor.

Códigos de error

• unauthorized: Falta la cabecera Authorization o la llave de API no es válida.
• scope_missing: Su llave no tiene permiso para esta operación.
• body_invalid: El cuerpo del pedido no se pudo leer.
• field_required: Faltan campos obligatorios.
• field_invalid: Hay campos con un valor inválido.
• method_unavailable: El método no está disponible para ese país y moneda.
• bank_unsupported: El banco indicado no admite este método.
• amount_out_of_range: El monto está fuera del rango permitido.
• currency_unsupported: La moneda no está disponible.
• country_unsupported: El país no está disponible.
• idempotency_key_reused: La clave de idempotencia ya se usó con otro pedido.
• idempotency_key_required: Falta la cabecera Idempotency-Key.
• not_found: No existe una operación con ese identificador.
• not_cancellable: La operación ya no se puede cancelar.
• code_not_expected: La operación no está esperando un código.
• too_many_codes: Se pidieron demasiados códigos para esta operación.
• temporarily_unavailable: No se pudo procesar en este momento. Intente más tarde.
• route_not_found: La ruta no existe.
• method_not_allowed: El método HTTP no está permitido en esta ruta.

Códigos de fallo

• counterparty_rejected: El banco del destinatario rechazó la operación.
• payer_insufficient_funds: El pagador no tiene fondos suficientes.
• mandate_required: El pagador todavía no autorizó el débito en su banco.
• code_rejected: El código no es válido o venció. Pida uno nuevo.
• limit_exceeded: El monto supera el límite permitido.
• outside_hours: Fuera del horario bancario.
• invalid_data: El banco no aceptó los datos de la operación. Revíselos y cree otra.
• expired: La operación venció.
• cancelled: La operación fue cancelada.
• temporarily_unavailable: No se pudo procesar en este momento. Intente más tarde.
• rejected: La operación fue rechazada.

Motivos que admite cada código (failure.reason): counterparty_rejected → invalid_account, account_closed, account_blocked, beneficiary_mismatch, invalid_phone, invalid_bank, invalid_document, other; payer_insufficient_funds → payer_insufficient_funds; mandate_required → no_mandate, mandate_revoked; code_rejected → code_invalid, code_expired; limit_exceeded → amount_over_limit, daily_limit; outside_hours → outside_hours; invalid_data → invalid_data; temporarily_unavailable → other, bank_offline, timeout; expired → expired; cancelled → cancelled; rejected → other.

Motivos de fallo

Cada código admite un conjunto fijo de motivos (failure.reason). other es «sin más detalle»: ahí el mensaje es el del código.

El motivo normalizado de un fallo, con el código al que pertenece:

• invalid_account (counterparty_rejected): La cuenta o el teléfono del destinatario no existe en su banco.
• account_closed (counterparty_rejected): La cuenta del destinatario está cerrada.
• account_blocked (counterparty_rejected): La cuenta del destinatario está bloqueada.
• beneficiary_mismatch (counterparty_rejected): Los datos del destinatario no corresponden a esa cuenta.
• invalid_phone (counterparty_rejected): El teléfono del destinatario no es válido para Pago Móvil.
• invalid_bank (counterparty_rejected): El banco del destinatario no existe o no recibe este tipo de operación.
• invalid_document (counterparty_rejected): El documento del destinatario no es válido.
• other (counterparty_rejected, temporarily_unavailable, rejected): Sin más detalle: vale el mensaje del código.
• payer_insufficient_funds (payer_insufficient_funds): El pagador no tiene fondos suficientes.
• code_invalid (code_rejected): El código no es válido.
• code_expired (code_rejected): El código venció.
• no_mandate (mandate_required): El pagador todavía no autorizó el débito en su banco.
• mandate_revoked (mandate_required): El pagador suspendió o revocó la autorización de débito.
• amount_over_limit (limit_exceeded): El monto supera el límite permitido para esta operación.
• daily_limit (limit_exceeded): Se superó el límite diario permitido.
• outside_hours (outside_hours): Fuera del horario bancario.
• invalid_data (invalid_data): El banco no aceptó los datos de la operación.
• bank_offline (temporarily_unavailable): El banco no está disponible en este momento.
• timeout (temporarily_unavailable): El banco no respondió a tiempo.
• expired (expired): La operación venció.
• cancelled (cancelled): La operación fue cancelada.

Los detalles de validación

Campo	Tipo	Obligatorio	Descripción
code	CodigoDeDetalle	sí
field	string	sí	La ruta del campo, con punto: payer.document.number, Idempotency-Key.

code de un detalle: required, invalid, unknown.

El sobre

Campo	Tipo	Obligatorio	Descripción
code	CodigoDeError	sí
details	array<Detalle>	no	Sólo en los errores de validación: un ítem por campo.
message	string	sí	Para mostrar, no para comparar.