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 los`shinkansen_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 los`shinkansen_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 mismos`message_id` y `transaction_id` del primer intento fallido**. De esa forma aseguras [idempotencia](#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_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 supera alguno de los límites impuestos por el banco o la red	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_account_closed	La cuenta de destino está cerrada, cancelada o bloqueada	Pídele a tu usuario final o a quien corresponda que use otra cuenta de destino 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_account_currency_mismatch	La moneda del pago no coincide con la de la cuenta de destino	Verifica la moneda de la cuenta de destino y, si corresponde, corrige los datos. 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ó.