Ir a contenido
Crea una cuenta
 o
Inicia sesión
Logotipo de Stripe Docs
/
Crear una cuenta
Iniciar sesión

Administración de errores

Capta y responde rechazos, datos no válidos, problemas de red, etc.

Copiar página

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 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.

TécnicaFinalidadCuándo se necesita
Captar excepcionesRecuperar una llamada API cuando esta no puede continuarSiempre
Supervisar webhooksReaccionar a las notificaciones de StripeA veces
Obtener información almacenada sobre erroresInvestigar problemas anteriores y admitir otras técnicasA veces

Captar excepciones

Si un problema inmediato impide que continúe una llamada API, la biblioteca Node.js de Stripe puede realizar una excepción. Capturar y gestionar las excepciones es una práctica recomendada. Para habilitarlas y captarlas, haz lo siguiente:

  • Si realizas una llamada API en una función, a la definición de la función antepón la palabra clave async.
  • Precede la llamada API misma con la palabra clave await.
  • Envuelve la llamada API en un bloque try/catch

Cuando captas una excepción, puedes usar el atributo Type para elegir una respuesta.

const stripe = require('stripe')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

async function exampleFunction(args) {
  try {
    const paymentIntent = await stripe.paymentIntents.create(args);
    console.log('No error.');
  } catch (e) {
    switch (e.type) {
      case 'StripeCardError':
        console.log(`A payment error occurred: ${e.message}`);
        break;
      case 'StripeInvalidRequestError':
        console.log('An invalid request occurred.');
        break;
      default:
        console.log('Another problem occurred, maybe unrelated to Stripe.');
        break;
    }
  }
}

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.

exampleFunction({
  // The required parameter currency is missing
  amount: 2000,
  confirm: true,
  payment_method: 
'pm_card_visa'
,
})
console
An invalid request occurred.

Supervisar webhooks

Stripe te notifica sobre muchos tipos de problemas utilizando webhooks. Esto incluye problemas que no se producen 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 falló. (El back-end sigue recibiendo notificaciones del webhook, aunque no haya sido el que realizó la llamada API).

No necesitas manejar todos los tipos de eventos de webhook. De hecho, algunas integraciones no manejan ninguna.

En tu controlador de webhook, comienza con los pasos básicos desde el creador de webhooks: obtén un objeto Event y usa el tipo de evento para descubrir qué sucedió. Luego, si el tipo de evento indica que ocurrió un error, debes seguir estos otros pasos:

  1. Ve a event.data.object para recuperar el objeto afectado.
  2. Usa información almacenada en el objeto afectado para obtener contexto, incluido un objeto Error.
  3. Usa el tipo de error para elegir una respuesta.
const stripe = require('stripe')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);
const express = require('express');
const app = express();

app.post('/webhook', express.json({type: 'application/json'}), (request, response) => {

  // Get an event object
  const event = request.body;

  // Use its type to find out what happened
  if (event.type == 'payment_intent.payment_failed') {

    // Get the object affected
    const paymentIntent = event.data.object;

    // Use stored information to get an error object
    const error = paymentIntent.last_payment_error;

    // Use its type to choose a response
    switch (error.type) {
      case 'card_error':
        console.log(`A payment error occurred: ${error.message}`);
        break;
      case 'invalid_request_error':
        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 manera local. Después de completar los pasos de configuración en ese enlace, activa 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.

Obtener información almacenada sobre errores

Muchos objetos almacenan información sobre errores. Eso significa que si algo ya salió mal, puedes recuperar el objeto y examinarlo para obtener más información. En muchos casos, la información almacenada tiene la forma de un objeto de error, y puedes usar su tipo para elegir una respuesta.

Por ejemplo:

  1. Recupera un Payment Intent específico.
  2. Para verificar si se produjo un error de pago, determina si last_payment_error está vacío.
  3. De ser así, registra el error. Incluye el tipo de error y el objeto afectado.
const stripe = require('stripe')(
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);

const payment_intent = await stripe.paymentIntents.retrieve(
'{{PAYMENT_INTENT_ID}}'
)

const e = payment_intent.last_payment_error

if (e !== null) {
  console.log(`PaymentIntent ${payment_intent.id} experienced a ${e.type} error.`)
}

Estos son algunos objetos comunes que almacenan información sobre errores.

ObjetoAtributoValores
Payment Intentlast_payment_errorUn objeto de error
Setup Intentlast_setup_errorUn objeto de error
Facturalast_finalization_errorUn objeto de error
Setup Attemptsetup_errorUn objeto de error
Payoutfailure_codeUn código de error de pago
Refundfailure_reasonUn código de error de reembolso

Para probar el código que usa información almacenada sobre errores, a menudo tendrás que simular transacciones fallidas. Por lo general, para hacerlo, usa tarjetas de prueba o números bancarios de prueba. Por ejemplo:

Tipos de errores y respuestas

En la biblioteca Stripe Node.js, cada objeto de error tiene un atributo type. Usa la documentación de cada tipo para obtener consejos sobre cómo responder.

Nombre

Tipo

Descripción
Error de pago

StripeCardError

Se produjo un error durante un pago, debido a alguno de estos motivos:
Errores de solicitud no válida

StripeInvalidRequestError

Hiciste una llamada API con parámetros erróneos, en el estado equivocado o de forma no válida.

Error de conexión

StripeConnectionError

Hubo un problema de red entre tu servidor y Stripe.
Error de API

StripeAPIError

Se produjo un error del lado de Stripe. (Esto no suele ocurrir).
Error de autenticación

StripeAuthenticationError

Stripe no puede autenticarte con la información proporcionada.
Error de idempotencia

StripeIdempotencyError

Utilizaste una clave de idempotencia para algo inesperado, como repetir una solicitud con parámetros distintos.
Error de permiso

StripePermissionError

La clave API usada para esta solicitud no tiene los permisos necesarios.
Error de límite de velocidad

StripeRateLimitError

Hiciste demasiadas llamadas API en muy poco tiempo.
Error de verificación de firma

StripeSignatureVerificationError

Estás usando la verificación de firma del webhook y no se pudo verificar que un evento de webhook sea auténtico.

Errores de pago

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:

Para distinguir estas categorías u obtener más información sobre cómo responder, consulta el código de error, el código de rechazo y el resultado del cargo.

(Para encontrar el resultado del cargo de un objeto Error, primero debes obtener el PaymentIntent involucrado y el último objeto Charge que creó. Consulta el siguiente ejemplo para ver una demostración).

const stripe = require('stripe')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

async function exampleFunction(args) {
    try {
      const paymentIntent = await stripe.paymentIntents.create(args);
    } catch (e) {
      console.log(e)
      const charge = await stripe.charges.retrieve(e.payment_intent.latest_charge)
      if (e.type === 'StripeCardError') {
        if (charge.outcome.type === 'blocked') {
          console.log('Payment blocked for suspected fraud.')
        } else if (e.code === 'card_declined') {
          console.log('Payment declined by the issuer.')
        } else if (e.code === 'expired_card') {
          console.log('Card expired.')
        } else {
          console.log('Other card error.')
        }
      }
    }
  }

Usuarios en la versión de API 2022-08-01 o anterior:

(Para encontrar el resultado del cargo de un objeto Error, primero debes obtener el PaymentIntent involucrado y el último objeto Charge que creó. Consulta el siguiente ejemplo para ver una demostración).

const stripe = require('stripe')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

async function exampleFunction(args) {
    try {
      const paymentIntent = await stripe.paymentIntents.create(args);
    } catch (e) {
      console.log(e)
      if (e.type === 'StripeCardError') {
        if (e.payment_intent.charges.data[0].outcome.type === 'blocked') {
          console.log('Payment blocked for suspected fraud.')
        } else if (e.code === 'card_declined') {
          console.log('Payment declined by the issuer.')
        } else if (e.code === 'expired_card') {
          console.log('Card expired.')
        } else {
          console.log('Other card error.')
        }
      }
    }
  }

Puedes activar algunos tipos de errores de pago más comunes con las tarjetas de prueba. Consulta la siguiente lista para ver las opciones:

El código de prueba que figura a continuación muestra algunas posibilidades.

exampleFunction({
  currency: 'usd',
  amount: 2000,
  confirm: true,
  payment_method: 
'pm_card_radarBlock'
,
})
console
Payment blocked for suspected fraud.

Pago bloqueado por presunto fraude

Tipo

StripeCardError

Códigos
const charge = await stripe.charges.retrieve(e.payment_intent.latest_charge)
charge.outcome.type === 'blocked'
Códigos

e.payment_intent.charges.data[0].outcome.type === 'blocked'

ProblemaEl sistema de prevención de fraude de Stripe, Radar, bloqueó el pago

Soluciones

Este error se puede producir cuando tu integración funciona correctamente. Cáptalo y solicítale al cliente otro método de pago.

Para bloquear menos pagos legítimos, intenta lo siguiente:

Los clientes de Radar para Equipos de Fraude tienen estas opciones adicionales:

  • Para eximir un pago en particular, agrégalo a tu lista de permitidos. Radar for Fraud Teams
  • Para modificar la tolerancia al riesgo, ajusta la configuración de riesgo. Radar para equipos de fraude
  • Para modificar los criterios de bloqueo de pagos, usa reglas personalizadas. Radar para equipos de fraude

Puedes probar los ajustes de tu integración con tarjetas de prueba que simulan fraude. Si estableciste reglas de Radar personalizadas, sigue los consejos de prueba de la documentación de Radar.

Pago rechazado por el emisor

Tipo

StripeCardError

Códigos

e.code === 'card_declined'

ProblemaEl emisor de la tarjeta rechazó el pago.

Soluciones

Este error puede ocurrir cuando tu integración funciona correctamente. Refleja una acción del emisor, y esa acción podría ser legítima. Usa el código de pago rechazado para determinar qué pasos debes seguir. Consulta la documentación sobre códigos de pago rechazado para ver las respuestas adecuadas para cada código.

También puedes

Prueba cómo tu integración gestiona los rechazos con tarjetas de prueba que simulan pagos correctos y pagos rechazados.

Otros errores de pago

Tipo

StripeCardError

ProblemaSe produjo otro error de pago.
SolucionesEste error puede ocurrir cuando tu integración funciona correctamente. Usa el código de error para determinar qué pasos debes seguir. Consulta la documentación sobre códigos de error para ver las respuestas adecuadas para cada código.

Errores de solicitudes no válidas

Tipo

StripeInvalidRequestError

ProblemaHiciste una llamada API con parámetros erróneos, en el estado equivocado o de forma no válida.
SolucionesEn 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.
  • Consulta la documentación sobre códigos de errores para obtener más información sobre el problema.
  • Para mayor comodidad, puedes seguir el 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 de cuál se trata.

Errores de conexión

Tipo

StripeAPIConnectionError

ProblemaHubo un problema de red entre tu servidor y Stripe.

Soluciones

Trata el resultado del llamada de API como indeterminado. Es decir, no asumas que tuvo éxito o que fracasó.

Para saber si se realizó correctamente, puedes

  • Recupera el objeto relevante desde Stripe y comprueba su estado.
  • Escucha la notificación de webhook que indica que la operación se realizó correctamente o falló.

Para ayudarte a recuperarte de errores de conexión, puedes hacer lo siguiente:

  • Al crear o actualizar un objeto, usa una clave de idempotencia. Luego, si se produce un error de conexión, puedes repetir la solicitud de forma segura sin riesgo de crear un segundo objeto o realizar la actualización dos veces. Repite la solicitud con la misma clave de idempotencia hasta que recibas una señal clara de éxito o falla. Para obtener asesoramiento avanzado sobre esta estrategia, consulta Gestión de errores de bajo nivel.
  • Habilita los reintentos automáticos. Luego, Stripe genera las claves de idempotencia y, cuando es seguro hacerlo, repite las solicitudes por ti.

Este error puede ocultar otros. Es posible que aparezca otro error después de que se resuelva el problema de conexión. Revisa que no haya errores en todas estas soluciones, al igual que lo harías en la solicitud original.

Errores de API

Tipo

StripeAPIError

ProblemaSe produjo un error del lado de Stripe. (Esto no suele ocurrir).

Soluciones

Trata el resultado de la llamada API como indeterminado. Es decir, no des por sentado que se realizó correctamente ni que falló.

Recurre a los webhooks para obtener información sobre el resultado. Cuando sea posible, Stripe activará webhooks para todos los objetos nuevos que se creen mientras se resuelva un problema.

Para configurar tu integración de manera que se comporte de la forma más sólida en situaciones inusuales, consulta esta página con información detallada sobre errores de servidores.

Errores de autenticación

Tipo

StripeAutheticationError

ProblemaStripe no puede autenticarte con la información proporcionada.
Soluciones

Errores de idempotencia

Tipo

StripeIdempotencyError

ProblemaUtilizaste una clave de idempotencia para algo inesperado, como repetir una solicitud con parámetros distintos.
Soluciones
  • Después de usar una clave de idempotencia, reutilízala solo para llamadas API idénticas.
  • Usa claves de idempotencia que no superen los 255 caracteres.

Errores de permisos

Tipo

StripePermissionError

ProblemaLa clave API usada para esta solicitud no tiene los permisos necesarios.
Soluciones
  • Asegúrate de no estar usando una clave de API restringida para un servicio al que no tiene acceso.
  • No realices acciones en el Dashboard si iniciaste sesión con una función de usuario que no tiene permiso para ella.

Errores de límite de frecuencia

Tipo

StripeRateLimitError

ProblemaHiciste demasiadas llamadas API en muy poco tiempo.
Soluciones
  • Si una sola llamada API activa este error, espera y vuelve a intentarlo.
  • Para gestionar el límite de velocidad de forma automática, reintenta la llamada API después de cierto tiempo. Aumenta exponencialmente ese período si el error persiste. Consulta la documentación sobre límites de frecuencia para obtener más consejos.
  • Si anticipas que tendrás un gran incremento del tráfico y quieres solicitar un aumento del límite de frecuencia, ponte en contacto con soporte por adelantado.

Errores de verificación de firma

Tipo

StripeSignatureVerificationError

ProblemaEstás usando la verificación de firma del webhook y no se pudo verificar que un evento de webhook sea auténtico.

Soluciones

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 y consideras que no debería ocurrir (por ejemplo, al usar webhooks que sabes que se originaron en Stripe), consulta la documentación sobre cómo verificar las firmas de webhooks. Asegúrate especialmente de estar usando el secreto del punto de conexión correcto. Esta clave es diferente de tu clave de API.

¿Te fue útil esta página?
SíNo
¿Necesitas ayuda? Ponte en contacto con soporte.
Únete a nuestro programa de acceso anticipado.
Echa un vistazo a nuestro registro de cambios.
¿Tienes alguna pregunta? Contacto.
¿LLM? Lee llms.txt.
Con tecnología de Markdoc