Guía
Start typing to search…

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_id y message_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_id y message_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 dinero
  • error: 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 mismostransaction_id y message_id.

Errores HTTP 4xx documentados

  • Proceder de acuerdo a la documentación del errror
  • Si llegaran a suceder errores 400 del tipo unprocessable_entity o bad_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 losshinkansen_transaction_id para cada id de transacción original que enviaste

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 losshinkansen_transaction_id para cada id de transacción original que enviaste

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 Retry-After que indica en cuantos segundos puedes enviar request nuevamente.

Reintenta después de los segundos indicados en la cabecera Retry-After.

👀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 mismosmessage_id y transaction_id del primer intento fallido. De esa forma aseguras idempotencia para no duplicar el mensaje. Si no reintentas corres el riesgo de que haya habido un problema de red después de que Shinkansen procesó tu mensaje

Qué hacer frente a cada response_status al recibir la respuesta de un payout

response_statusQué significaQué hago
okTodo OKMarca el payout como exitoso en tus registros.
invalidFalló 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_mismatchAlgo está mal con los datos de la cuenta de destinoPí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_limitsLa cuenta de destino está bloqueada o no tiene fondos suficientesPí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_offlineEl banco de destino o la red están fuera de líneaSi 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_limitsLa cuenta de origen está superando alguno de los límites impuestos por el banco o la redRevisa 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_fundsLa cuenta de origen no tiene fondos suficientesFondea 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_expiredSe 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.
errorAlgo 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 15 days ago