Ir a contenido
Crea una cuenta
o
Inicia sesión
Logotipo de Stripe Docs
/
Pregúntale a la IA
Crear una cuenta
Iniciar sesión
Empieza ahora
Pagos
Ingresos
Plataformas y marketplaces
Gestión del dinero
Herramientas para desarrolladores
Resumen
Control de versiones
Registro de cambios
Actualiza tu versión de API
Actualiza la 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 frecuencia
    Pruebas automatizadas
    Metadatos
    Cómo expandir respuestas
    Paginación
    Dominios y direcciones IP
    Buscar
    Localización
    Administración de errores
      Gestión de errores avanzados
    Códigos de error
Pruebas
Workbench
Destinos de eventos
Flujos de trabajo
CLI de Stripe
Stripe Shell
Dashboard para desarrolladores
Kit de herramientas para agentes
Desarrolla con LLMStripe para Visual Studio CodeAlertas de estado de StripeCargas de archivos
Seguridad y privacidad
Seguridad
Privacidad
Amplía Stripe
Stripe Apps
Stripe Connectors
Socios
Ecosistema de socios
Certificación de socio
InicioHerramientas para desarrolladoresAPI

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

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 poco frecuente de que necesites datos HTTP, consulta cómo gestionar las excepciones de bajo nivel y el objeto Error.

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

Si el valor de error está relacionado con Stripe, puedes convertirlo en un objeto stripe.Error, que tiene campos que describen el problema. Usa el campo 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.

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

Ir
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
Ir
1749847553 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. 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 Error.
  3. Usa el tipo de error para elegir una respuesta.
Ir
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 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.
Ir
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) }

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:

  • Simula un pago rechazado para crear errores de Charges, PaymentIntents y SetupIntents, entre otros.
  • Simula un error de pago.
  • Simula un error de reembolso.

Tipos de errores y respuestas

En la biblioteca Stripe Go, 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

stripe.ErrorTypeCard

Se produjo 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

Hiciste una llamada API de una forma que no es válida en este momento. El motivo puede haber sido alguno de estos:

  • Error de límite de frecuencia
  • 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

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

Errores de tarjetas

Errores de pago sin tarjeta

Todo lo dispuesto 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. Pero, de hecho, 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 Error, primero debes obtener el PaymentIntent involucrado y el último objeto 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 Error, primero debes obtener el PaymentIntent involucrado y el último objeto 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 de errores de pago más comunes con las tarjetas de prueba. Consulta la siguiente lista para ver las opciones:

  • Cómo simular pagos bloqueados por riesgo de fraude
  • Cómo simular 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
1749847553 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, 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:

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

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.

Rechazado por el emisor

Tipo

stripe.ErrorTypeCard

Códigos

cardErr.Error.Code == stripe.ErrorCodeCardDeclined

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

  • Sigue las recomendaciones para reducir los rechazos de los emisores.
  • Usa Payment Links, Checkout o Stripe Elements para los elementos de formulario prediseñados que implementan esas recomendaciones.

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

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

Los errores de solicitudes no válidas pueden ocurrir por varios motivos. El más común es que la solicitud API tenga parámetros no válidos o que no esté permitida en el estado actual de tu integración. Usa el código de error (stripeErr.Code) y consulta la documentación sobre códigos de errores para encontrar una solución. Algunos códigos de errores exigen una respuesta especial:

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

Errores de límite de frecuencia

Tipo

stripe.ErrorTypeInvalidRequest

CódigosstripeErr.Code == stripe.ErrorCodeRateLimit or stripeErr.Code == stripe.ErrorCodeLockTimeout
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 autenticación

Tipo

stripe.ErrorTypeInvalidRequest

CódigosstripeErr.Code == stripe.ErrorCodeSecretKeyRequired
ProblemaStripe no puede autenticarte con la información proporcionada.
Soluciones
  • Usa 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
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 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 de cuál se trata.

Errores de API

Tipo

stripe.ErrorTypeAPI

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 idempotencia

Tipo

stripe.ErrorTypeIdempotency

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