Payouts - ¿Cómo manejar los errores?
🚧 Principios Generales
- Toda invocación debe ser idempotente: si deseas repetir un intento, debes enviar los mismos identificadores (
transaction_idymessage_id). - Para todo escenario fuera del flujo normal o que lo interrumpa, y en el cual no se tiene certeza de la recepción de la transacción por parte de Shinkansen, debes considerar reintentar el envío del mensaje con las transacciones utilizando los mismos identificadores (
transaction_idymessage_id).
✅ Estados posibles de una payout
Un payout en Shinkansen sólo puede estar en uno de tres estados:
pending: Estado inicial, es un transacción "en vuelo" y aún no ha sido resuelto si ha movido dinero o no.ok: Procesada exitosamente, la transacción mueve dineroerror: Fallo definitivo en la ejecución, la transacción no mueve dinero.
📡 Recomendaciones para manejo de errores al enviar un mensaje de payouts a Shinkansen
Errores HTTP 5xx
- Debes considerar la transacción en un estado unknown (indefinido).
- Reintentar el envío con los mismos
transaction_idymessage_id.
Errores HTTP 4xx documentados
- Proceder de acuerdo a la documentación del errror
- Si llegaran a suceder errores 400 del tipo
unprocessable_entityobad_request, el error debe ser analizado en detalle, pero si se desea reintentar, se deben conservar los mismos transaction_idymessage_id`
Errores no documentados, desconexiones y timeouts
- No asumas que el mensaje de payouts no fue recepcionado por Shinkansen
- Siempre reintentar usando los mismos identificadores.
Qué hacer frente a cada respuesta HTTP al enviar un payout
HTTP Error Code | Qué significa | Qué hago |
|---|---|---|
200 | Todo OK | Revisa la respuesta para 💾 guardar los |
400 | Algo no superó una validación | 👀 Mira el contenido de la respuesta, que te indica qué es lo que está mal que puede ser que la firma no sea válida o hubo algún problema de validación. Corrígelo e intenta enviar otro mensaje (puedes usar los mismos ids de mensajes y transacciones si quieres) |
403 | Permiso denegado | Probablemente está errada tu API key o no tienes acceso a el producto Payouts para ese banco. 👨🏻💻Si todo funcionaba OK y luego te aparece este error, contáctanos para revisar qué pasó. |
409 | El payout ya fue enviado, pero está todo OK | Significa que la idempotencia funcionó y que seguramente estabas reintentando el envío de un mensaje. Revisa la respuesta para 💾 guardar los |
429 | Too Many Request, en el caso de que muchos request lleguen seguidos, puedes recibir un error 429 cuando se activen los protocolos de defensa automáticos. En la respuesta puedes encontrar un header | Reintenta después de los segundos indicados en la cabecera 👀Como Shinkansen no impone rate limits muy agresivos, si llegas a ver este error varias veces te recomendamos que nos contactes via Slack, Chat en el Dashboard o Email para revisar en conjunto tu situación. |
5xx o cualquier código inesperado o un timeout | Algo inesperado ocurrió | 🔄 Reintenta el envío del mensaje usando los mismos |
Qué hacer frente a cada response_status al recibir la respuesta de un payout
response_status al recibir la respuesta de un payoutresponse_status | Qué significa | Qué hago |
|---|---|---|
ok | Todo OK | Marca el payout como exitoso en tus registros. |
invalid | Falló alguna validación (no todas las validaciones se realizan al recibir un mensaje) | Revisa el contenido de la respuesta para ver qué es lo que está mal. Corrígelo e intenta enviar otro mensaje con nuevomessage_id y nuevotransaction_id (pues la transacción original ya ha terminado con este error). |
error_creditor_account_not_found o error_creditor_account_detail_mismatch | Algo está mal con los datos de la cuenta de destino | Pídele a tu usuario final o a quien corresponda que corrija los datos de la cuenta. Luego intenta enviar otro mensaje con nuevomessage_id y nuevotransaction_id (pues la transacción original ya ha terminado con este error). |
error_creditor_account_over_limits | La cuenta de destino está bloqueada o no tiene fondos suficientes | Pídele a tu usuario final o a quien corresponda que corrija los datos de la cuenta o resuelva la situación con su banco. Luego intenta enviar otro mensaje con nuevomessage_id y nuevotransaction_id (pues la transacción original ya ha terminado con este error). |
error_creditor_fi_offline o error_payment_rail_offline | El banco de destino o la red están fuera de línea | Si tu pago es urgente, reintenta en 30-60 segundos. Si no es tan urgente, recomendamos reintentar en 5-30 minutos. Si puedes implementar exponential back-off, mejor aún. En cualquier caso, cada reintento debe ser con nuevomessage_id y nuevotransaction_id (pues la transacción original ya ha terminado con este error). |
error_debtor_account_over_limits | La cuenta de origen está superando alguno de los límites impuestos por el banco o la red | Revisa con el banco qué límites estás superando para subirlos si tiene sentido. Nosotros felices de ayudarte en ese proceso también. |
error_debtor_insufficient_funds | La cuenta de origen no tiene fondos suficientes | Fondea la cuenta de origen y luego intenta enviar otro mensaje con nuevomessage_id y nuevotransaction_id (pues la transacción original ya ha terminado con este error). |
error_delivery_ttl_expired | Se superó el tiempo máximo que especificaste para enviar el mensaje (si incluiste el campo ttl en una transacción de payout) | La acción dependerá de la razón para incluir un ttl en la transacción original. Por ejemplo, podrías querer ejecutar el pago manualmente pasado un cierto tiempo máximo en que no se haya enviado la transacción al banco por problemas de indisponibilidad o capacidad de procesamiento del mismo. |
error | Algo inesperado ocurrió | Si tu pago es urgente, reintenta en 30-60 segundos. Si no es tan urgente, recomendamos reintentar en 5-30 minutos. Si puedes implementar exponential back-off, mejor aún. En cualquier caso, cada reintento debe ser con nuevomessage_id y nuevotransaction_id (pues la transacción original ya ha terminado con este error). Si después de 5 intentos la transacción sigue fallando y el camporesponse_message no te da ninguna pista, contáctanos para revisar qué pasó. |
Updated 2 days ago