Ir a contenido
Crea una cuenta
o
inicia sesión
Logotipo de la documentación de Stripe
/
Pregúntale a la IA
Crear cuenta
Iniciar sesión
Empezar
Pagos
Ingresos
Plataformas y marketplaces
Gestión del dinero
Herramientas para desarrolladores
Resumen
Control de versiones
Registro de cambios
Actualiza tu versión de la API
Mejora tu versión de SDK
Herramientas para desarrolladores
SDK
API
    API v2
    Claves de API
    Encabezado de Stripe-Context
    Registro de cambios diario
    Límites de velocidad
    Pruebas automatizadas
    Metadatos
    Cómo expandir las respuestas
    Paginación
    Dominios y direcciones IP
    Buscar
    Localización
    Administración de errores
      Tratamiento de errores avanzados
    Códigos de error
Pruebas
Espacio de trabajo
Destinos de eventos
Flujos de trabajo
CLI de Stripe
Stripe Shell
Dashboard de desarrolladores
Kit de herramientas para agentes
Crear con LLMStripe para Visual Studio CodeAlertas de estado de StripeCargas de archivos
Seguridad y privacidad
Seguridad
Privacidad
Ampliar Stripe
Stripe Apps
Stripe Connectors
Socios
Ecosistema de socios
Certificación de socio
InicioHerramientas para desarrolladoresAPI

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
Usar valores de erroresRecuperar 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

Usar valores de errores

Errores y HTTP

Con esta biblioteca no es necesario buscar respuestas HTTP distintas de 200. La biblioteca las traduce a valores de errores.

En el caso improbable de que necesites detalles de HTTP, consulta Cómo gestionar las excepciones de bajo nivel y el objeto Error.

Las llamadas a la API en la biblioteca de Go de Stripe devuelven tanto un valor de resultado como un valor de error. Usa varias asignaciones para capturar ambos. Si el valor de error no es nil, significa que un problema inmediato ha evitado que la llamada a la API continuara.

Si el valor de error está relacionado con Stripe, puedes convertirlo a un objeto stripe.Error, que tiene campos para describir el problema. Usa el campo de tipo para elegir una respuesta. En algunos casos, puedes forzar la propiedad Err a un tipo de error más específico con información adicional.

Go
package main import ( "github.com/stripe/stripe-go/v72" "github.com/stripe/stripe-go/v72/paymentintent" "log" ) func example_function(params *stripe.PaymentIntentParams) { stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
_, err := paymentintent.New(params) if err == nil { log.Println("No error.") } else { if stripeErr, ok := err.(*stripe.Error); ok { switch stripeErr.Type { case stripe.ErrorTypeCard: log.Println("A payment error occurred:", stripeErr.Msg) case stripe.ErrorTypeInvalidRequest: log.Println("An invalid request occurred.") default: log.Println("Another Stripe error occurred.") } } else { log.Println("An error occurred that was unrelated to Stripe.") } } }

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.

Go
params := &stripe.PaymentIntentParams{ Amount: stripe.Int64(2000), // The required parameter currency is missing Confirm: stripe.Bool(true), PaymentMethod: stripe.String(
"pm_card_visa"
), } example_function(params)
console
Go
1749848468 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. Obtén el objeto afectado convirtiendo los datos mediante el proceso de unmarshalling desde event.Data.Raw.
  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.
Go
package main import ( "encoding/json" "io/ioutil" "log" "net/http" "github.com/stripe/stripe-go/v72" "github.com/stripe/stripe-go/v72/webhook" ) func main() { http.HandleFunc("/webhook", handleWebhook) addr := "localhost:4242" log.Printf("Listening on %s", addr) log.Fatal(http.ListenAndServe(addr, nil)) } func handleWebhook(w http.ResponseWriter, req *http.Request) { const MaxBodyBytes = int64(65536) req.Body = http.MaxBytesReader(w, req.Body, MaxBodyBytes) payload, err := ioutil.ReadAll(req.Body) if err != nil { log.Printf("Error reading request body: %v\n", err) w.WriteHeader(http.StatusServiceUnavailable) return } // Replace this endpoint secret with your endpoint's unique secret // If you are testing with the CLI, find the secret by running 'stripe listen' // If you are using an endpoint defined with the API or dashboard, look in your webhook settings // at https://dashboard.stripe.com/webhooks endpointSecret := "whsec_..." signatureHeader := req.Header.Get("Stripe-Signature") // Get an event object event, err := webhook.ConstructEvent(payload, signatureHeader, endpointSecret) if err != nil { log.Printf("⚠️ Webhook signature verification failed. %v\n", err) w.WriteHeader(http.StatusBadRequest) // Return a 400 error on a bad signature return } // Use its type to find out what happened switch event.Type { case "payment_intent.payment_failed": // Get the object affected by unmarshalling event data into // the appropriate struct for the event type var paymentIntent stripe.PaymentIntent err := json.Unmarshal(event.Data.Raw, &paymentIntent) if err != nil { log.Printf("Error parsing webhook JSON: %v\n", err) w.WriteHeader(http.StatusBadRequest) return } // Use stored data to get an error object e := paymentIntent.LastPaymentError // Use its type to choose a response switch e.Type { case "card_error": log.Println("A payment error occurred: ", e.Msg) case "invalid_request": log.Println("An invalid request occurred.") default: log.Println("Another problem occurred, maybe unrelated to Stripe.") } default: log.Println("Unhandled event type: ", event.Type) } w.WriteHeader(http.StatusOK) }

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.
Go
stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
pi, _ := paymentintent.Get(
"{{PAYMENT_INTENT_ID}}"
, nil, ) paymentErr := pi.LastPaymentError if paymentErr != nil { log.Printf("PaymentIntent %s experienced a %s error.", pi.ID, paymentErr.Type) }

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:

  • Simular un pago rechazado, para crear Cargos, PaymentIntents, SetupIntents, etc. fallidos.
  • Simula una transferencia fallida.
  • Simula un reembolso fallido.

Tipos de errores y respuestas

En la biblioteca de Go de Stripe, cada objeto de error tiene un atributo Type. Utiliza la documentación de cada tipo para ver consejos sobre cómo responder.

Nombre

Tipo

Descripción
Error de pago

stripe.ErrorTypeCard

Se ha producido un error durante un pago debido a alguno de estos motivos:
  • Pago bloqueado por presunto fraude
  • Pago rechazado por el emisor.
  • Otros errores de pago.
Errores de solicitud no válida

stripe.ErrorTypeInvalidRequest

Has hecho una llamada a la API de una forma que no es válida en este momento. El motivo puede haber sido alguno de los siguientes:

  • Error de límite de velocidad
  • Error de autenticación
  • Estado o parámetro no válido
Error de API

stripe.ErrorTypeAPI

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

stripe.ErrorTypeIdempotency

Has usado una clave de idempotencia para una acción inesperada, como repetir una solicitud con parámetros distintos.

Errores de tarjetas

Errores de pago sin tarjeta

Todo lo incluido en esta sección también se aplica a los pagos sin tarjeta. Por razones históricas, los errores de pago tienen el tipo stripe. ErrorTypeCard. Sin embargo, la realidad es que pueden representar un problema con cualquier pago, independientemente del método 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:

  • Pago bloqueado por presunto fraude
  • Pago rechazado por el emisor
  • Otros errores de pago

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 de error, primero debes obtener el PaymentIntent en cuestión y el último Charge que creó. Consulta el siguiente ejemplo para ver una demostración).

Go
func example_function(params *stripe.PaymentIntentParams) { stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
_, err := paymentintent.New(params) if err == nil { log.Println("No error.") } else { if stripeErr, ok := err.(*stripe.Error); ok { if stripeErr.Type == stripe.ErrorTypeCard { charge = Charge.retrieve(stripeErr.PaymentIntent.LatestCharge) if charge.Outcome.Type == "blocked" { log.Println("Payment blocked for suspected fraud.") } else if stripeErr.Code == stripe.ErrorCodeCardDeclined { log.Println("Declined by the issuer.") } else if stripeErr.Code == stripe.ErrorCodeExpiredCard { log.Println("Card expired.") } else { log.Println("Other card error.") } } } } }

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

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

Go
func example_function(params *stripe.PaymentIntentParams) { stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
_, err := paymentintent.New(params) if err == nil { log.Println("No error.") } else { if stripeErr, ok := err.(*stripe.Error); ok { if stripeErr.Type == stripe.ErrorTypeCard { if stripeErr.PaymentIntent.Charges.Data[0].Outcome.Type == "blocked" { log.Println("Payment blocked for suspected fraud.") } else if stripeErr.Code == stripe.ErrorCodeCardDeclined { log.Println("Declined by the issuer.") } else if stripeErr.Code == stripe.ErrorCodeExpiredCard { log.Println("Card expired.") } else { log.Println("Other card error.") } } } } }

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

  • Simulación de pagos bloqueados por riesgo de fraude
  • Simulación de pagos rechazados y otros errores de tarjeta

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

Go
params := &stripe.PaymentIntentParams{ Amount: stripe.Int64(2000), Currency: stripe.String(string(stripe.CurrencyUSD)), Confirm: stripe.Bool(true), PaymentMethod: stripe.String(
"pm_card_radarBlock"
), } example_function(params)
console
Go
1749848468 Payment blocked for suspected fraud.

Bloqueado por presunto fraude

Tipo

stripe.ErrorTypeCard

Códigos
charge = Charge.retrieve(stripeErr.PaymentIntent.LatestCharge) charge.Outcome.Type == "blocked"
Códigos

stripeErr.PaymentIntent.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:

  • Optimiza tu integración con Radar para recolectar información más detallada.
  • Usa Payment Links, Checkout o Stripe Elements para elementos de formularios prediseñados y optimizados.

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
  • Para cambiar tu tolerancia al riesgo, ajusta tu configuración de riesgo. Radar for Fraud Teams
  • Para cambiar los criterios de bloqueo de un pago, usa reglas personalizadas. Radar for Fraud Teams

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

Rechazado por el emisor

Tipo

stripe.ErrorTypeCard

Códigos

cardErr.Error.Code == stripe.ErrorCodeCardDeclined

ProblemaEl emisor de la tarjeta ha rechazado el pago.

Soluciones

Este error puede ocurrir cuando tu integración funciona correctamente. Refleja una acción por parte del emisor, y esa acción podría ser legítima. Usa el código de rechazo para determinar los pasos a seguir que correspondan. Consulta la documentación sobre códigos de rechazo para obtener respuestas apropiadas para cada código.

También puedes:

  • Sigue las recomendaciones para reducir los pagos rechazados del emisor.
  • Usa Payment Links, Checkout o Stripe Elements para elementos de formularios prediseñados que implementan las recomendaciones.

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

Otros errores de pago

Tipo

stripe.ErrorTypeCard

ProblemaSe produjo otro error de pago.
SolucionesEste error puede ocurrir cuando tu integración funciona correctamente. Usa el código de error para determinar los pasos a seguir correspondientes. Consulta la documentación sobre códigos de error para obtener respuestas apropiadas para cada código.

Errores de solicitudes no válidas

Los errores de solicitud no válida cubren varias situaciones. La más común es aquella en la que la petición a la API tiene parámetros no válidos o no está permitida con el estado actual de tu integración. Utiliza el código de error (stripeErr.Code) y consulta la documentación de código de error para encontrar una solución. Algunos códigos de error requieren una respuesta especial:

  • rate_limit y lock_timeout reflejan errores de límite de velocidad
  • secret_key_required refleja un error de autenticación
  • Otros códigos de error reflejan parámetros o estados no válidos

Errores de límite de velocidad

Tipo

stripe.ErrorTypeInvalidRequest

CódigosstripeErr.Code == stripe.ErrorCodeRateLimit or stripeErr.Code == stripe.ErrorCodeLockTimeout
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.
  • Para gestionar el límite de velocidad automáticamente, 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ímites de velocidad para obtener 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, Contacta con soporte por adelantado.

Errores de autenticación

Tipo

stripe.ErrorTypeInvalidRequest

CódigosstripeErr.Code == stripe.ErrorCodeSecretKeyRequired
ProblemaStripe no puede autenticarte con la información proporcionada.
Soluciones
  • Utiliza la clave de API correcta.
  • Asegúrate de no estar usando una clave que hayas «rotado» o anulado.

Estado o parámetro inválido

Tipo

stripe.ErrorTypeInvalidRequest

CódigosstripeErr.Code != stripe.ErrorCodeRateLimit and stripeErr.Code != stripe.ErrorCodeLockTimeout and stripeErr.Code != stripe.ErrorCodeSecretKeyRequired
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.
  • Consulta la documentación de códigos de error para obtener más información sobre el problema.
  • Para mayor comodidad, puedes acceder al enlace stripeErr.DocURL para ver la documentación sobre el código de error.
  • Si el error involucra un parámetro específico, usa stripeErr.Param para determinar cuál.

Errores de API

Tipo

stripe.ErrorTypeAPI

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.

Para configurar tu integración para que sea lo más estable posible en situaciones inusuales, consulta este análisis avanzado de errores de servidor.

Errores de idempotencia

Tipo

stripe.ErrorTypeIdempotency

ProblemaHas usado una clave de idempotencia para una acción inesperada, como repetir una solicitud con parámetros distintos.
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.
¿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