Administración de errores

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

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écnica	Finalidad	Cuándo se necesita
Captar excepciones	Recuperar una llamada API cuando esta no puede continuar	Siempre
Supervisar webhooks	Reaccionar a las notificaciones de Stripe	A veces
Obtener información almacenada sobre errores	Investigar problemas anteriores y admitir otras técnicas	A veces

Captar excepciones

Si un problema inmediato impide que continúe una llamada a la API, la biblioteca Java de Stripe genera una excepción. Es una buena práctica detectar y gestionar las excepciones.

Para detectar una excepción, usa la sintaxis try/catch de Java. Capta StripeException o sus subclases para gestionar solo las excepciones específicas de Stripe. Cada subclase representa un tipo diferente de excepción. Cuando detectes una excepción, puedes usar su clase para elegir una respuesta.

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.

Error de activación:

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:

Obtén el objeto afectado usando un EventDataObjectDeserializer y convierte el resultado al tipo de error adecuado.
Usa información almacenada en el objeto afectado para obtener contexto, incluido un objeto Error.
Usa el tipo de error para elegir una respuesta.

Java
post("/webhook", (request, response) -> {
      String payload = request.body();
      String sigHeader = request.headers("Stripe-Signature");
      String endpointSecret = "whsec_9d75cc10168ca3f518f64a69a5015bc07222290a199b27985efe350c7c59ecde";

      Event event = null;

      // Get an event object
      try {
        event = Webhook.constructEvent(payload, sigHeader, endpointSecret);
      } catch (SignatureVerificationException e) {
        response.status(400);
        return "";
      }

      // Deserialize the object inside the event to a generic Stripe object
      EventDataObjectDeserializer dataObjectDeserializer = event.getDataObjectDeserializer();
      StripeObject stripeObject = null;
      if (dataObjectDeserializer.getObject().isPresent()) {
        stripeObject = dataObjectDeserializer.getObject().get();
      } else {
        // Deserialization failed, probably due to an API version mismatch.
        // Refer to the Javadoc documentation on `EventDataObjectDeserializer` for
        // instructions on how to handle this case, or return an error here.
      }

      // Use the event type to find out whaat happened
      switch (event.getType()) {
        case "payment_intent.payment_failed":

          // Get the object affected by casting the generic Stripe object
          PaymentIntent paymentIntent = (PaymentIntent) stripeObject;

          // Use stored information to get an error object
          StripeError error = paymentIntent.getLastPaymentError();

          // Use its type to choose a response
          switch(error.getType()) {
            case "card_error":
              System.out.printf("A payment error occurred: %s\n", error.getMessage());
              break;
            case "invalid_request":
              System.out.println("An invalid request occurred.");
              break;
            default:
              System.out.println("Another problem occurred, maybe unrelated to Stripe.");
              break;
          }
          break;
        default:
          // Unexpected event type
          response.status(400);
          return "";
      }

      response.status(200);
      return "";
    });
  }

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:

Recupera un Payment Intent específico.
Para verificar si se produjo un error de pago, determina si last_payment_error está vacío.
De ser así, registra el error. Incluye el tipo de error y el objeto afectado.

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

Objeto	Atributo	Valores
Payment Intent	`last_payment_error`	Un objeto de error
Setup Intent	`last_setup_error`	Un objeto de error
Factura	`last_finalization_error`	Un objeto de error
Setup Attempt	`setup_error`	Un objeto de error
Payout	`failure_code`	Un código de error de pago
Refund	`failure_reason`	Un 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 de Stripe Java, cada tipo de error pertenece a su propia clase. Usa la documentación de cada clase para obtener consejos sobre cómo responder.

Nombre	Clase	Descripción
Error de pago	CardException	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	InvalidRequestException	Hiciste una llamada API con parámetros erróneos, en el estado equivocado o de forma no válida.
Error de conexión	ApiConnectionException	Hubo un problema de red entre tu servidor y Stripe.
Error de API	APIException	Se produjo un error del lado de Stripe. (Esto no suele ocurrir).
Error de autenticación	AuthenticationException	Stripe no puede autenticarte con la información proporcionada.
Error de idempotencia	IdempotencyException	You used an idempotency key for something unexpected, like replaying a request but passing different parameters.
Error de permiso	PermissionException	La clave API usada para esta solicitud no tiene los permisos necesarios.
Error de límite de velocidad	RateLimitException	Hiciste demasiadas llamadas API en muy poco tiempo.
Error de verificación de firma	SignatureVerificationException	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:

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

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

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

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.

Error de activación:

Pago bloqueado por presunto fraude

Tipo	`CardException`
Códigos	`Charge charge = Charge.retrieve(ex.getStripeError() .getPaymentIntent() .getLatestCharge()); charge.getOutcome().getType() == "blocked"`
Códigos	`ex.getStripeError().getPaymentIntent().getCharges().getData().get(0).getOutcome().getType() == "blocked"`
Problema	El 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: Optimize your Radar integration to collect more detailed information. Use Payment Links, Checkout, or Stripe Elements for prebuilt optimized form 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 To change your risk tolerance, adjust your risk settings. Radar para Equipos de Fraude To change the criteria for blocking a payment, use custom rules. Radar para Equipos de Fraude 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	`CardException`
Códigos	`e.getCode() == "card_declined"`
Problema	El emisor de la tarjeta rechazó el pago.
Soluciones	This error can occur when your integration is working correctly. It reflects an action by the issuer, and that action may 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 Follow recommendations to reduce issuer declines. Use Payment Links, Checkout, or Stripe Elements for prebuilt form elements that implement those recommendations. Test how your integration handles declines with test cards that simulate successful and declined payments.

Otros errores de pago

Tipo	`CardException`
Problema	Se produjo otro error de pago.
Soluciones	This 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	`InvalidRequestException`
Problema	Hiciste una llamada 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. Consult the error code documentation for details on the problem. Para mayor comodidad, puedes seguir el enlace `e.getDocUrl()` para ver la documentación sobre el código de error. Si el error involucra un parámetro específico, usa `e.getParam()` para determinar de cuál se trata.

Errores de conexión

Tipo	`APIConnectionException`
Problema	Hubo un problema de red entre tu servidor y Stripe.
Soluciones	Trata el resultado de la llamada API como indeterminado. Es decir, no des por sentado que se realizó correctamente ni que falló. 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ó. 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. 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.

Tipo

APIConnectionException

Problema Hubo un problema de red entre tu servidor y Stripe.

Soluciones

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

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

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.
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	`APIException`
Problema	Se 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. To set your integration up for maximum robustness in unusual situations, see this advanced discussion of server errors.

Tipo

APIException

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

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

Errores de autenticación

Tipo	`AuthenticationException`
Problema	Stripe no puede autenticarte con la información proporcionada.
Soluciones	Use the correct API key. Make sure you aren’t using a key that you “rotated” or revoked.

Errores de idempotencia

Tipo	`IdempotencyException`
Problema	You 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 API idénticas. Usa claves de idempotencia que no superen los 255 caracteres.

Errores de permisos

Tipo	`PermissionException`
Problema	La clave API usada para esta solicitud no tiene los permisos necesarios.
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 frecuencia

Tipo	`RateLimitException`
Problema	Hiciste demasiadas llamadas API en muy poco tiempo.
Soluciones	Si una sola llamada 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 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	`SignatureVerificationException`
Problema	You’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.

Tipo

SignatureVerificationException

Problema You’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.