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 CodeQué significaQué hago
200Todo OKRevisa la respuesta para 💾 guardar los shinkansen_transaction_id para cada id de transacción original que enviaste
400Algo 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)
403Permiso denegadoProbablemente 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ó.
409El payout ya fue enviado, pero está todo OKSignifica 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
429Too 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. Si llegas a ver este error, comunícate con nosotros para revisar el caso particular.
5xx o cualquier código inesperado o un timeoutAlgo 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_codeQué 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 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_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 nuevo message_id y nuevo transaction_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 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_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 nuevo message_id y nuevo transaction_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 nuevo message_id y nuevo transaction_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 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ó.