Payouts - ¿Cómo manejar los errores?

Qué hacer con errores HTTP o response_codes en respuestas

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. 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 la firma del mensaje. 👨🏻‍💻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	Ratelimit de Cloudflare, en el caso de que muchos request lleguen seguidos, Cloudflare puede lanzar 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. Si llegas a ver este error, comunícate con nosotros para revisar el caso particular.
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 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_code` al recibir la respuesta de un payout

`response_code`	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 nuevo `message_id` y nuevo `transaction_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 nuevo `message_id` y nuevo `transaction_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 nuevo `message_id` y nuevo `transaction_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 nuevo `message_id` y nuevo `transaction_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 nuevo `message_id` y nuevo `transaction_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 nuevo `message_id` y nuevo `transaction_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 campo `response_message` no te da ninguna pista, contáctanos para revisar qué pasó.

Updated 2 months ago