Captura y responde a pagos rechazados, datos no válidos, problemas de red y mucho más.
Stripe ofrece varios tipos de errores. Estos pueden reflejar eventos externos, como pagos fallidos e interrupciones de redes, o problemas de código, como llamadas a la API no válidas.
Para gestionar errores, usa todas o algunas de las técnicas de la tabla que figura a continuación. Sea cual sea la técnica que uses, puedes seguir con nuestras respuestas recomendadas para cada tipo de error.
Investigar problemas pasados y aceptar otras técnicas
A veces
Reconocer excepciones
Si un problema inmediato evita que continúe una llamada a la API, la biblioteca de Node.js de Stripe puede lanzar una excepción. Capturar y gestionar las excepciones es una práctica recomendada. Para habilitar el lanzamiento de excepciones y captarlas, debes seguir estos pasos:
Si haces la llamada a la API en una función, precede la definición de la función con la palabra clave async.
Precede la llamada a la API con la palabra clave await.
Envolver la llamada a la API en un bloque try/catch
Después de configurar la gestión de excepciones, pruébala con varios datos, incluidas las tarjetas de prueba, para simular diferentes resultados de pago.
Stripe te notifica sobre varios tipos de problemas mediante los webhooks. Entre ellos, se incluyen los problemas que no ocurren inmediatamente después de una llamada a la API. Por ejemplo:
Pierdes una disputa.
Un pago recurrente falla después de haberse cobrado correctamente durante meses.
Tu front-end confirma un pago, pero se desconecta antes de saber que el pago ha fallado. (El back-end sigue recibiendo notificaciones del webhook, aunque no haya sido el que hizo la llamada a la API).
No necesitas manejar todos los tipos de eventos de webhook. De hecho, algunas integraciones no manejan ninguno.
En tu controlador de webhook, comienza siguiendo los pasos básicos desde el creador de webhooks: obtén un objeto de evento y usa el tipo de evento para descubrir qué sucedió. Luego, si el tipo de evento indica que hubo un error, debes seguir estos pasos adicionales:
);const express =require('express');const app =express();
app.post('/webhook', express.json({type:'application/json'}),(request, response)=>{// Get an event objectconst event = request.body;// Use its type to find out what happenedif(event.type=='payment_intent.payment_failed'){// Get the object affectedconst paymentIntent = event.data.object;// Use stored information to get an error objectconst error = paymentIntent.error;// Use its type to choose a responseswitch(error.type){case'StripeCardError':
console.log(`A payment error occurred: ${error.message}`);break;case'StripeInvalidRequestError':
console.log('An invalid request occurred.');if(error.param){
console.log(`The parameter ${error.param} is invalid or missing.`);}break;default:
console.log('Another problem occurred, maybe unrelated to Stripe.');break;}}
response.send();});
app.listen(4242,()=> console.log('Running on port 4242'));
Para probar cómo responde tu integración a los eventos de webhook, puedes activar eventos de webhook de forma local. Después de completar los pasos de configuración en ese enlace, lleva a cabo un pago fallido para ver el mensaje de error resultante.
Command Line
stripe trigger payment_intent.payment_failed
Output
A payment error occurred: Your card was declined.
Obtén información almacenada sobre errores
Muchos objetos almacenan información sobre errores. Esto significa que, si ya ha habido un problema, puedes recuperar el objeto y revisarlo para obtener más información. En muchos casos, la información almacenada se presenta en forma de un objeto de error, por lo que puedes usar el tipo de error para elegir una respuesta.
Por ejemplo:
Recupera un Payment Intent específico.
Comprueba si experimentó un error de pago determinando si last_payment_error está vacío.
Si lo hizo, registra el error, incluido su tipo y el objeto afectado.
Para probar código que usa información almacenada sobre errores, a menudo tendrás que simular transacciones fallidas. Por lo general, puedes hacerlo usando tarjetas de prueba o números bancarios de prueba. Por ejemplo:
En la biblioteca de Node.js de Stripe, cada objeto de error tiene un atributo type. Utiliza la documentación de cada tipo para ver consejos sobre cómo responder.
Los errores de pago, a veces llamados «errores de tarjeta» por motivos históricos, cubren una amplia variedad de problemas comunes. Están divididos en tres categorías:
Este error puede ocurrir cuando tu integración funciona correctamente. Refleja una acción por parte del emisor, y que la acción puede ser legítima. Utiliza el código de rechazo para determinar los pasos apropiados. Consulta la documentación sobre códigos de rechazo para obtener respuestas apropiadas para cada código.
Este error puede ocurrir cuando tu integración funciona correctamente. Utiliza el código de error para determinar los pasos apropiados. Consulta la documentación sobre códigos de error para obtener respuestas apropiadas para cada código.
Errores de solicitudes no válidas
Tipo
StripeInvalidRequestError
Problema
Has hecho una llamada a la API con parámetros erróneos, en el estado equivocado o de forma no válida.
Soluciones
En la mayoría de los casos, el problema es de la solicitud misma. Puede ser que los parámetros no sean válidos o que la solicitud no pueda realizarse en el estado actual de tu integración.
Para mayor comodidad, puedes acceder al enlace e.doc_url para ver la documentación sobre el código de error.
Si el error involucra un parámetro específico, usa e.param para determinar cuál.
Errores de conexión
Tipo
StripeAPIConnectionError
Problema
Ha habido un problema de red entre tu servidor y Stripe.
Soluciones
Trata el resultado de la llamada a la API como indeterminado. Es decir, no des por sentado que se ha llevado a cabo correctamente ni que ha fallado.
Para saber si se ha llevado a cabo correctamente, puedes hacer lo siguiente:
Recupera el objeto relevante desde Stripe y comprueba su estado.
Escucha la notificación del webhook que indica que la operación se ha llevado a cabo correctamente o que ha fallado.
Para facilitar la recuperación después de errores de conexión, puedes hacer lo siguiente:
Al crear o actualizar un objeto, usa una clave de idempotencia. De este modo, si se produce un error de conexión, puedes repetir la solicitud de forma segura sin riesgo de crear un segundo objeto ni de realizar la actualización dos veces. Repite la solicitud con la misma clave de idempotencia hasta que recibas una respuesta clara de éxito o fracaso. Para obtener consejos avanzados sobre esta estrategia, consulta Manejo de errores de bajo nivel.
Activa los reintentos automáticos. A continuación, Stripe te genera claves de idempotencia y te repite las solicitudes cuando sea seguro hacerlo.
Este error puede encubrir otros. Es posible que, cuando se resuelva el error de conexión, se manifieste algún otro error. Comprueba si hay errores en todas estas soluciones igual que lo harías en la solicitud original.
Errores de API
Tipo
StripeAPIError
Problema
Se ha producido un error del lado de Stripe. (Esto no suele ocurrir).
Soluciones
Trata el resultado de la llamada a la API como indeterminado. Es decir, no des por sentado que se ha llevado a cabo correctamente ni que ha fallado.
Recurre a los webhooks para obtener información sobre el resultado. Cuando es posible, Stripe activa webhooks para todos los objetos nuevos que se crean mientras se resuelve un problema.
Are you performing an action in the Dashboard while logged in as a user role that lacks permission?
Errores de límite de velocidad
Tipo
StripeRateLimitError
Problema
Has hecho demasiadas llamadas a la API en muy poco tiempo.
Soluciones
Si una sola llamada a la API activa este error, espera y vuelve a intentarlo.
Para gestionar el límite de velocidad de forma automática, reintenta la llamada a la API después de cierto tiempo. Aumenta exponencialmente ese período si el error persiste. Consulta la documentación sobre límite de velocidad para leer más consejos.
Si anticipas que vas a tener un gran incremento del tráfico y quieres solicitar un aumento del límite de velocidad, ponte en contacto con soporte por adelantado.
Este error puede ocurrir cuando tu integración funciona correctamente. Si usas una verificación de firma de webhook y un tercero intenta enviarte un webhook falso o malicioso, entonces la verificación falla y, como resultado, se devuelve este error. Cáptalo y responde con un código de estado 400 Bad Request.
Si recibes este error cuando no deberías, por ejemplo, con webhooks que sabes que se originan en Stripe, consulta la documentación sobre verificación de firmas de webhooks para obtener más información. En particular, comprueba que estés usando el secreto de punto de conexión correcto. Es diferente de la clave API.
Welcome to the Stripe Shell!
Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Log in to your
Stripe account and press Control + Backtick (`) on your keyboard to start managing your Stripe
resources in test mode.
- View supported Stripe commands:
- Find webhook events:
- Listen for webhook events:
- Call Stripe APIs: stripe [api resource] [operation] (e.g., )
La experiencia con Stripe Shell es mejor en ordenadores de sobremesa.