Errores, comprobaciones de estado y reintentos
Inspeccione siempre tanto la respuesta HTTP como la transacción status. Un 200 o 201 puede contener una transacción rechazada o pendiente.
| Resultado HTTP | Acción de integración |
|---|---|
| 400 / 422 | Verifique los campos proporcionados, tipos, escala de monto y destinatario. No volver a enviar errores de validación sin cambios en un bucle |
| 401 | Verifica la credencial, su validez y el host API |
| 403 | La cuenta o clave autenticada carece de permiso; no cambiar de cuenta automáticamente |
| 404 | Verifique el identificador y el contexto de la cuenta. Esto no prueba que otra cuenta no tenga ese recurso |
| 409 | Inspeccione el conflicto y recupere la operación original antes de crear cualquier otra cosa |
| 429 | Respete Retry-After cuando esté presente y vuelva a intentar las lecturas con retroceso acotado |
| Timeout / 5xx | El resultado puede ser desconocido. Busque la operación original de id o txid antes de volver a enviar |
Las formas de respuesta de error pueden diferir según el punto final. Prefiera un código de error documentado y legible por máquina, cuando esté disponible; error_description es texto legible por humanos y no un código estable. Elimine u oculte las credenciales y los datos de instrumentos de pago en los registros.
Resultados de la transacción
charged: la transacción se completó exitosamente.rejectedofailed: inspeccionar el motivo y el funcionamiento original; no reporte éxito.refundedoreversed: los fondos tienen un resultado diferente al de un pago recién liquidado.- Estado pendiente/acción requerida/desconocido: muestra ese estado y la acción requerida del usuario. Nunca infieras el éxito únicamente a partir de un estado no reconocido o de una marca de tiempo.
Utilice transacción GET para verificar una operación. Mantenga el mismo txid para reintentos de la misma instrucción comercial. Las fallas en la entrega del webhook y una falla en el procesamiento de pagos son eventos diferentes.