Ir a contenido
Crea una cuenta
 o
inicia sesión
Logotipo de la documentación de Stripe
/
Crear cuenta
Iniciar sesión

Administración de errores

Captura y responde a pagos rechazados, datos no válidos, problemas de red y mucho más.

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

TécnicaFinalidadEn caso necesario
Excepciones de capturaRecuperar una llamada a la API cuando esta no puede continuarSiempre
Controlar los webhooksReaccionar a las notificaciones de StripeA veces
Obtener información almacenada sobre fallosInvestigar problemas pasados y aceptar otras técnicasA veces

Reconocer excepciones

Si un problema inmediato evita que continúe una llamada a la API, la biblioteca de Ruby de Stripe lanza una excepción. Captar y gestionar las excepciones es una práctica recomendada.

Para atrapar una excepción, usa la palabra clave rescue de Ruby. Captura Stripe::StripeError o sus subclases para manejar solo las excepciones específicas de Stripe. Cada subclase representa un tipo diferente de excepción. Cuando detectes una excepción, podrás usar su clase para elegir una respuesta.

require 'stripe'

Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


def example_function(params)
  begin
    Stripe::PaymentIntent.create(params)
  rescue Stripe::CardError => e
    puts "A payment error occurred: #{e.error.message}"
  rescue Stripe::InvalidRequestError => e
    puts "An invalid request occurred."
  rescue Stripe::StripeError => e
    puts "Another problem occurred, maybe unrelated to Stripe."
  else
    puts "No error."
  end
end

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.

example_function(
  # The required parameter currency is missing,
  amount: 2000,
  confirm: true,
  payment_method: 
'pm_card_visa'
,
)
console
An invalid request occurred.

Controlar los webhooks

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é ha suciedido. Luego, si el tipo de evento indica que se ha producido un error, debes seguir estos pasos adicionales:

  1. Accede a event.data.object para recuperar el objeto afectado.
  2. Usa información almacenada en el objeto afectado para obtener contexto, incluido un objeto de error.
  3. Use su tipo para elegir una respuesta.
require 'stripe'
require 'sinatra'
post '/webhook' do
  payload = request.body.read
  data = JSON.parse(payload, symbolize_names: true)

  # Get the event object
  event = Stripe::Event.construct_from(data)

  # Use the event type to find out what happened
  case event.type
  when 'payment_intent.payment_failed'

    # Get the object affected
    payment_intent = event.data.object

    # Use stored information to get an error object
    e = payment_intent.last_payment_error

    # Use its type to choose a response
    case e.type
    when 'card_error'
      puts "A payment error occurred: #{e.message}"
    when 'invalid_request'
      puts "An invalid request occurred."
    else
      puts "Another problem occurred, maybe unrelated to Stripe."
    end
  end

  content_type 'application/json'
  {
    status: 'success'
  }.to_json
end

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, efectúa 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:

  1. Recupera un Payment Intent específico.
  2. Comprueba si se ha producido un error en el pago determinando si last_payment_error está vacío.
  3. Si lo hizo, registra el error, incluido su tipo y el objeto afectado.
require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


payment_intent = Stripe::PaymentIntent.retrieve(
'{{PAYMENT_INTENT_ID}}'
)
e = payment_intent.last_payment_error
if !e.nil?
  puts "PaymentIntent #{payment_intent.id} experienced a #{e.type}."
end

Aquí hay objetos comunes que almacenan información sobre fallos.

ObjetoAtributoValores
Payment Intentlast_payment_errorUn objeto de error
Setup Intentlast_setup_errorUn objeto de error
Facturalast_finalization_errorUn objeto de error
Intento de configuraciónsetup_errorUn objeto de error
Transferenciafailure_codeUn código de error de transferencia
Reembolsarfailure_reasonUn código de reembolso fallido

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:

Tipos de errores y respuestas

En la biblioteca de Ruby de Stripe, los objetos de error son parte de stripe.error.StripeError y sus subclases. Utiliza la documentación de cada clase para ver consejos sobre cómo responder.

Nombre

Clase

Descripción
Error de pago

Stripe::CardError

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

Stripe::InvalidRequestError

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

Error de conexión

Stripe::APIConnectionError

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

Stripe::APIError

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

Stripe::AuthenticationError

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

Stripe::IdempotencyError

You used an idempotency key for something unexpected, like replaying a request but passing different parameters.
Error de permiso

Stripe::PermissionError

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

Stripe::RateLimitError

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

Stripe::SignatureVerificationError

You’re using webhook signature verification and couldn’t verify that a webhook event is authentic.

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:

To distinguish these categories or get more information about how to respond, consult the error code, decline code, and charge outcome.

(To find the charge outcome from an error object, first get the Payment Intent that’s involved and the latest Charge it created. See the example below for a demonstration.)

require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


def example_function(params)
  begin
    Stripe::PaymentIntent.create(params)
  rescue Stripe::CardError => e
    charge = Stripe::Charge.retrieve(e.error.payment_intent.latest_charge)
    if charge.outcome.type == 'blocked'
      puts 'Payment blocked for suspected fraud.'
    elsif e.code == 'card_declined'
      puts 'Payment declined by the issuer.'
    elsif e.code == 'expired_card'
      puts 'Card expired.'
    else
      puts 'Other card error.'
    end
  end
end

Users on API version 2022-08-01 or older:

(To find the charge outcome from an error object, first get the Payment Intent that’s involved and the latest Charge it created. See the example below for a demonstration.)

require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


def example_function(params)
  begin
    Stripe::PaymentIntent.create(params)
  rescue Stripe::CardError => e
    if e.error.payment_intent.charges.data[0].outcome.type == 'blocked'
      puts 'Payment blocked for suspected fraud.'
    elsif e.code == 'card_declined'
      puts 'Payment declined by the issuer.'
    elsif e.code == 'expired_card'
      puts 'Card expired.'
    else
      puts 'Other card error.'
    end
  end
end

Puedes activar algunos tipos habituales de error de pago con tarjetas de prueba. Consulta las opciones en estas listas:

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

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

Pago bloqueado por presunto fraude

Tipo

Stripe::CardError

Códigos
charge = Stripe::Charge.retrieve(e.error.payment_intent.latest_charge)
charge.outcome.type == 'blocked'
Códigos

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

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

Soluciones

Este error se puede producir cuando tu integración esté funcionando 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 for Fraud Teams tienen estas opciones adicionales:

  • Para eximir un pago en particular, añádelo a tu lista de permitidos. Radar for Fraud Teams
  • To change your risk tolerance, adjust your risk settings. Radar for Fraud Teams
  • To change the criteria for blocking a payment, use custom rules. Radar for Fraud Teams

You can test your integration’s settings with test cards that simulate fraud. If you have custom Radar rules, follow the testing advice in the Radar documentation.

Pago rechazado por el emisor

Tipo

Stripe::CardError

Códigos

e.error.code == "card_declined"

ProblemaEl emisor de la tarjeta ha rechazado el pago.

Soluciones

This error can occur when your integration is working correctly. It reflects an action by the issuer, and that action might be legitimate. Use the decline code to determine what next steps are appropriate. See the documentation on decline codes for appropriate responses to each code.

También puedes:

Test how your integration handles declines with test cards that simulate successful and declined payments.

Otros errores de pago

Tipo

Stripe::CardError

ProblemaSe produjo otro error de pago.
SolucionesThis error can occur when your integration is working correctly. Use the error code to determine what next steps are appropriate. See the documentation on error codes for appropriate responses to each code.

Errores de solicitudes no válidas

Tipo

Stripe::InvalidRequestError

ProblemaHas hecho una llamada a la 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.
  • Consult the error code documentation for details on the problem.
  • Para mayor comodidad, puedes acceder al enlace para ver la documentación sobre el código de error.
  • Si el error involucra un parámetro específico, usa para determinar cuál.

Errores de conexión

Tipo

Stripe::APIConnectionError

ProblemaHa habido un problema de red entre tu servidor y Stripe.

Soluciones

Treat the result of the API call as indeterminate. That is, don’t assume that it succeeded or that it failed.

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.

To help recover from connection errors, you can:

  • When creating or updating an object, use an idempotency key. Then, if a connection error occurs, you can safely repeat the request without risk of creating a second object or performing the update twice. Repeat the request with the same idempotency key until you receive a clear success or failure. For advanced advice on this strategy, see Low-level error handling.
  • 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

Stripe::APIError

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

To set your integration up for maximum robustness in unusual situations, see this advanced discussion of server errors.

Errores de autenticación

Tipo

Stripe::AuthenticationError

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

Errores de idempotencia

Tipo

Stripe::IdempotencyError

ProblemaYou used an idempotency key for something unexpected, like replaying a request but passing different parameters.
Soluciones
  • Después de usar una clave de idempotencia, reutilízala solo para llamadas a la API idénticas.
  • Usa claves de idempotencia que no superen los 255 caracteres.

Errores de permisos

Tipo

Stripe::PermissionError

ProblemaThe API key used for this request doesn’t have the necessary permissions.
Soluciones
  • Make sure you aren’t using a restricted API key for a service it doesn’t have access to.
  • Don’t perform actions in the Dashboard while logged in as a user role that lacks permission.

Errores de límite de velocidad

Tipo

Stripe::RateLimitError

ProblemaHas 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.
  • To handle rate-limiting automatically, retry the API call after a delay, and increase the delay exponentially if the error continues. See the documentation on rate limits for further advice.
  • Si anticipas que vas a tener un gran incremento del tráfico y quieres solicitar un aumento del límite de velocidad, Contacta con soporte por adelantado.

Errores de verificación de firma

Tipo

Stripe::SignatureVerificationError

ProblemaYou’re using webhook signature verification and couldn’t verify that a webhook event is authentic.

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.

If you receive this error when you shouldn’t—for instance, with webhooks that you know originate with Stripe—then see the documentation on checking webhook signatures for further advice. In particular, make sure you’re using the correct endpoint secret. This is different from your API key.

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