# Administración de errores Captura y responde a pagos rechazados, datos no válidos, problemas de red y mucho más. 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. ## Analiza los datos de error Cuando Stripe devuelve un error a tu petición de API, recibirás detalles sobre el error que te ayudarán a entender cómo aplicar las sugerencias de gestión en esta guía. Estos datos también te ayudan a proporcionar información importante al soporte de Stripe, si la necesitas. | Propiedad | Descripción | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | El código de error. | | `doc_url` | Un enlace a la documentación de Stripe para el código de error específico. | | `message` | Una descripción del motivo del error. | | `param` | El parámetro de la petición que causó el error. | | `request_log_url` | Un enlace al Dashboard de Stripe, donde podrás ver registros detallados sobre la petición inicial y el error. | | ID de la petición | Un identificador único para la petición inicial que ha producido el error. El encabezado de respuesta de error incluye este valor (cadena que comienza por `req`), pero puedes especificar una impresión en tu petición, como se muestra en los ejemplos de código de esta guía. | | `type` | Referencia a la categoría de error a la que pertenece este error. | 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](https://docs.stripe.com/error-handling.md#error-types). | Técnica | Finalidad | En caso necesario | | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------- | | [Excepciones de captura](https://docs.stripe.com/error-handling.md#catch-exceptions) | Recuperar una llamada a la API cuando esta no puede continuar | Siempre | | [Controlar los webhooks](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reaccionar a las notificaciones de Stripe | A veces | | [Obtener información almacenada sobre fallos](https://docs.stripe.com/error-handling.md#use-stored-information) | Investigar problemas pasados y aceptar otras técnicas | A veces | ## Reconocer excepciones Con esta biblioteca no es necesario buscar respuestas HTTP distintas de 200. La biblioteca las traduce como excepciones. En el caso improbable de que necesites detalles de HTTP, consulta [Cómo gestionar las excepciones de bajo nivel](https://docs.stripe.com/error-low-level.md) y el objeto [Error](https://docs.stripe.com/api/errors.md). 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](https://docs.stripe.com/error-handling.md#error-types). | Técnica | Finalidad | En caso necesario | | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------- | | [Excepciones de captura](https://docs.stripe.com/error-handling.md#catch-exceptions) | Recuperar una llamada a la API cuando esta no puede continuar | Siempre | | [Controlar los webhooks](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reaccionar a las notificaciones de Stripe | A veces | | [Obtener información almacenada sobre fallos](https://docs.stripe.com/error-handling.md#use-stored-information) | Investigar problemas pasados y aceptar otras técnicas | A veces | ## Reconocer excepciones Con esta biblioteca no es necesario buscar respuestas HTTP distintas de 200. La biblioteca las traduce como excepciones. En el caso improbable de que necesites detalles de HTTP, consulta [Cómo gestionar las excepciones de bajo nivel](https://docs.stripe.com/error-low-level.md) y el objeto [Error](https://docs.stripe.com/api/errors.md). Si un problema inmediato evita que continúe una llamada a la API, la biblioteca de Python de Stripe lanza una excepción. Captar y gestionar las excepciones es una práctica recomendada. Para capturar una excepción, usa la sintaxis `try`/`except` de Python. 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, puedes [usar su clase para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). | Técnica | Finalidad | En caso necesario | | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------- | | [Excepciones de captura](https://docs.stripe.com/error-handling.md#catch-exceptions) | Recuperar una llamada a la API cuando esta no puede continuar | Siempre | | [Controlar los webhooks](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reaccionar a las notificaciones de Stripe | A veces | | [Obtener información almacenada sobre fallos](https://docs.stripe.com/error-handling.md#use-stored-information) | Investigar problemas pasados y aceptar otras técnicas | A veces | ## Reconocer excepciones Con esta biblioteca no es necesario buscar respuestas HTTP distintas de 200. La biblioteca las traduce como excepciones. En el caso improbable de que necesites detalles de HTTP, consulta [Cómo gestionar las excepciones de bajo nivel](https://docs.stripe.com/error-low-level.md) y el objeto [Error](https://docs.stripe.com/api/errors.md). Si un problema inmediato evita que continúe una llamada a la API, la biblioteca de PHP de Stripe lanza una excepción. Captar y gestionar las excepciones es una práctica recomendada. Para captar una excepción, usa la sintaxis `try`/`catch` de PHP. Stripe ofrece varias clases de excepciones que puedes captar. Cada una representa un tipo diferente de error. Cuando captas una excepción, puedes [usar su clase para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). | Técnica | Finalidad | En caso necesario | | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------- | | [Excepciones de captura](https://docs.stripe.com/error-handling.md#catch-exceptions) | Recuperar una llamada a la API cuando esta no puede continuar | Siempre | | [Controlar los webhooks](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reaccionar a las notificaciones de Stripe | A veces | | [Obtener información almacenada sobre fallos](https://docs.stripe.com/error-handling.md#use-stored-information) | Investigar problemas pasados y aceptar otras técnicas | A veces | ## Reconocer excepciones Con esta biblioteca no es necesario buscar respuestas HTTP distintas de 200. La biblioteca las traduce como excepciones. En el caso improbable de que necesites detalles de HTTP, consulta [Cómo gestionar las excepciones de bajo nivel](https://docs.stripe.com/error-low-level.md) y el objeto [Error](https://docs.stripe.com/api/errors.md). Si un problema inmediato evita que continúe una llamada a la API, la biblioteca de Java de Stripe lanza una excepción. Captar y gestionar las excepciones es una práctica recomendada. Para atrapar una excepción, usa la sintaxis `try`/`catch` de Java. Captura `StripeException` o sus subclases para manejar solo las excepciones específicas de Stripe. Cada subclase representa un tipo diferente de excepción. Cuando detectas una excepción, puedes [usar su clase para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). | Técnica | Finalidad | En caso necesario | | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------- | | [Excepciones de captura](https://docs.stripe.com/error-handling.md#catch-exceptions) | Recuperar una llamada a la API cuando esta no puede continuar | Siempre | | [Controlar los webhooks](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reaccionar a las notificaciones de Stripe | A veces | | [Obtener información almacenada sobre fallos](https://docs.stripe.com/error-handling.md#use-stored-information) | Investigar problemas pasados y aceptar otras técnicas | A veces | ## Reconocer excepciones Con esta biblioteca no es necesario buscar respuestas HTTP distintas de 200. La biblioteca las traduce como excepciones. En el caso improbable de que necesites detalles de HTTP, consulta [Cómo gestionar las excepciones de bajo nivel](https://docs.stripe.com/error-low-level.md) y el objeto [Error](https://docs.stripe.com/api/errors.md). Si un problema inmediato impide que continúe una llamada a la API, la biblioteca de Stripe para Node.js puede generar una excepción. Capturar y gestionar las excepciones es una práctica recomendada. Para habilitar la generación de excepciones y capturarlas, sigue estos pasos: - Si haces la llamada a la API en una función, precede la definición de la función con la palabra clave `async`. - Precede la llamada a la API con la palabra clave `await`. - Envolver la llamada a la API en un bloque `try`/`catch` Cuando detectas una excepción, puedes [usar su atributo type para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). | Técnica | Finalidad | En caso necesario | | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------- | | [Usar valores de errores](https://docs.stripe.com/error-handling.md#catch-exceptions) | Recuperar una llamada a la API cuando esta no puede continuar | Siempre | | [Controlar los webhooks](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reaccionar a las notificaciones de Stripe | A veces | | [Obtener información almacenada sobre fallos](https://docs.stripe.com/error-handling.md#use-stored-information) | Investigar problemas pasados y aceptar otras técnicas | A veces | ## Usar valores de errores 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](https://docs.stripe.com/error-low-level.md) y el objeto [Error](https://docs.stripe.com/api/errors.md). 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](https://docs.stripe.com/error-handling.md#error-types). En algunos casos, puedes forzar la propiedad `Err` a un tipo de error más específico con información adicional. | Técnica | Finalidad | En caso necesario | | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------- | | [Excepciones de captura](https://docs.stripe.com/error-handling.md#catch-exceptions) | Recuperar una llamada a la API cuando esta no puede continuar | Siempre | | [Controlar los webhooks](https://docs.stripe.com/error-handling.md#monitor-webhooks) | Reaccionar a las notificaciones de Stripe | A veces | | [Obtener información almacenada sobre fallos](https://docs.stripe.com/error-handling.md#use-stored-information) | Investigar problemas pasados y aceptar otras técnicas | A veces | ## Reconocer excepciones Con esta biblioteca no es necesario buscar respuestas HTTP distintas de 200. La biblioteca las traduce como excepciones. En el caso improbable de que necesites detalles de HTTP, consulta [Cómo gestionar las excepciones de bajo nivel](https://docs.stripe.com/error-low-level.md) y el objeto [Error](https://docs.stripe.com/api/errors.md). Si un problema inmediato evita que continúe una llamada a la API, la biblioteca de .NET de Stripe lanza una excepción. Capturar y gestionar las excepciones es una práctica recomendada. Para capturar una excepción, usa la sintaxis `try`/`catch` de .NET. Captura una `StripeException` y luego [usa su atributo Type para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); error_log("No error."); } catch(\Stripe\Exception\CardException $e) { error_log("A payment error occurred: {$e->getError()->message}. (request id: {$e->getRequestId()})"); } catch (\Stripe\Exception\InvalidRequestException $e) { error_log("An invalid request occurred. (request id: {$e->getRequestId()})"); // Add additional catch cases for other Stripe exception types as needed. // See all exception types at https://docs.stripe.com/api/errors/handling?lang=php } catch (\Stripe\Exception\ApiErrorException $e) { // All other Stripe API errors error_log("Status: " . $e->getHttpStatus() . ", Code: " . $e->getStripeCode() . ", Message: " . $e->getMessage() . ", Request ID: " . $e->getRequestId()); } catch (Exception $e) { error_log("Another problem occurred, maybe unrelated to Stripe."); } } ``` Después de configurar la gestión de excepciones, pruébala con varios datos, incluidas las [tarjetas de prueba](https://docs.stripe.com/testing.md), para simular diferentes resultados de pago. #### Error al activar - Petición no válida #### PHP ```php example_function([ // The required parameter currency is missing 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa', // Esta es una tarjeta de prueba que siempre funciona correctamente cuando la usas en entornos de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` An invalid request occurred. ``` #### Error al activar - Error de tarjeta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedFraudulent', // Esta es una tarjeta de prueba que siempre produce un error de pago por cargo fraudulento. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` A payment error occurred: Your card was declined. ``` #### Error al activar - Sin error #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa', // Esta es una tarjeta de prueba que siempre funciona correctamente cuando la usas en entornos de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` No error. ``` ## Controlar los webhooks Stripe te notifica sobre varios tipos de problemas mediante los *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests). 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* (Confirming a PaymentIntent indicates that the customer intends to pay with the current or provided payment method. Upon confirmation, the PaymentIntent attempts to initiate a payment) 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](https://docs.stripe.com/webhooks/quickstart.md): 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](https://docs.stripe.com/api/events/object.md#event_object-data-object) para recuperar el objeto afectado. 1. [Usa información almacenada](https://docs.stripe.com/error-handling.md#use-stored-information) en el objeto afectado para obtener contexto, incluido un objeto de error. 1. [Use su tipo para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). 1. Accede a [event[‘data’][‘object’]](https://docs.stripe.com/api/events/object.md#event_object-data-object) para recuperar el objeto afectado. 1. [Usa información almacenada](https://docs.stripe.com/error-handling.md#use-stored-information) en el objeto afectado para obtener contexto, incluido un objeto de error. 1. [Use su tipo para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). 1. Accede a [event->data->object](https://docs.stripe.com/api/events/object.md#event_object-data-object) para recuperar el objeto afectado. 1. [Usa información almacenada](https://docs.stripe.com/error-handling.md#use-stored-information) en el objeto afectado para obtener contexto, incluido un objeto de error. 1. [Use su tipo para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). 1. Obtén el objeto afectado usando un `EventDataObjectDeserializer` y enviando su salida al tipo apropiado. 1. [Usa información almacenada](https://docs.stripe.com/error-handling.md#use-stored-information) en el objeto afectado para obtener contexto, incluido un objeto de error. 1. [Use su tipo para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). 1. Accede a [event.data.object](https://docs.stripe.com/api/events/object.md#event_object-data-object) para recuperar el objeto afectado. 1. [Usa información almacenada](https://docs.stripe.com/error-handling.md#use-stored-information) en el objeto afectado para obtener contexto, incluido un objeto de error. 1. [Use su tipo para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). 1. Obtén el objeto afectado convirtiendo los datos mediante el proceso de unmarshalling desde `event.Data.Raw`. 1. [Usa información almacenada](https://docs.stripe.com/error-handling.md#use-stored-information) en el objeto afectado para obtener contexto, incluido un objeto de error. 1. [Use su tipo para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). 1. Obtén el objeto afectado enviando [stripeEvent.Data.Object](https://docs.stripe.com/api/events/object.md#event_object-data-object) al tipo apropiado. 1. [Usa información almacenada](https://docs.stripe.com/error-handling.md#use-stored-information) en el objeto afectado para obtener contexto, incluido un objeto de error. 1. [Use su tipo para elegir una respuesta](https://docs.stripe.com/error-handling.md#error-types). #### PHP ```php >'); $payload = @file_get_contents('php://input'); $event = null; // Get the event object try { $event = \Stripe\Event::constructFrom( json_decode($payload, true) ); } catch(\UnexpectedValueException $e) { echo '⚠️ Webhook error while parsing basic request.'; http_response_code(400); exit(); } // Use the event type to find out what happened if ($event->type == 'payment_intent.payment_failed') { // Get the object affected $paymentIntent = $event->data->object; // Use stored information to get an error object $e = $paymentIntent->last_payment_error; // Use its type to choose a response switch ($e->type) { case \Stripe\Exception\CardException: error_log("A payment error occurred: {$e->getError()->message}"); break; case \Stripe\Exception\InvalidRequestException: error_log("An invalid request occurred."); if (isset($e->getError()->param)) { error_log("The parameter {$e->getError()->param} is invalid or missing."); } break; default: error_log("Another problem occurred, maybe unrelated to Stripe."); } } http_response_code(200); ``` Para probar cómo responde tu integración a los eventos de webhook, puedes [activar eventos de webhook de forma local](https://docs.stripe.com/webhooks.md#test-webhook). Después de completar los pasos de configuración en ese enlace, efectúa un pago fallido para ver el mensaje de error resultante. ```bash stripe trigger payment_intent.payment_failed ``` ```bash 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](https://docs.stripe.com/error-handling.md#error-types). Por ejemplo: 1. Recupera un Payment Intent específico. 1. Comprueba si se ha producido un error en el pago determinando si [last_payment_error](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-last_payment_error) está vacío. 1. Si lo hizo, registra el error, incluido su tipo y el objeto afectado. #### PHP ```php >'); $payment_intent = $stripe->paymentIntents->retrieve(% identifier type="paymentIntent" /%}); $e = $payment_intent->last_payment_error; if (isset($e)) { error_log("PaymentIntent {$payment_intent->id} experienced a {$e->getError()->type} error."); } ``` Aquí hay objetos comunes que almacenan información sobre fallos. | Objeto | Atributo | Valores | | ------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------ | | [Payment Intent](https://docs.stripe.com/api/payment_intents.md) | `last_payment_error` | [Un objeto de error](https://docs.stripe.com/error-handling.md#work-with-error-objects) | | [Setup Intent](https://docs.stripe.com/api/setup_intents.md) | `last_setup_error` | [Un objeto de error](https://docs.stripe.com/error-handling.md#work-with-error-objects) | | [Factura](https://docs.stripe.com/api/invoices.md) | `last_finalization_error` | [Un objeto de error](https://docs.stripe.com/error-handling.md#work-with-error-objects) | | [Intento de configuración](https://docs.stripe.com/api/setup_attempts.md) | `setup_error` | [Un objeto de error](https://docs.stripe.com/error-handling.md#work-with-error-objects) | | [Transferencia](https://docs.stripe.com/api/payouts.md) | `failure_code` | [Un código de error de transferencia](https://docs.stripe.com/api/payouts/failures.md) | | [Reembolsar](https://docs.stripe.com/api/refunds.md) | `failure_reason` | [Un código de reembolso fallido](https://docs.stripe.com/api/refunds/object.md#refund_object-failure_reason) | 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](https://docs.stripe.com/testing.md) o números bancarios de prueba. Por ejemplo: - [Simular un pago rechazado](https://docs.stripe.com/testing.md#declined-payments), para crear Cargos, PaymentIntents, SetupIntents, etc. fallidos. - [Simula una transferencia fallida](https://docs.stripe.com/connect/testing.md#account-numbers). - [Simula un reembolso fallido](https://docs.stripe.com/testing.md#refunds). ## 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](https://docs.stripe.com/error-handling.md#payment-errors) | Se ha producido un error durante un pago debido a alguno de estos motivos: - [Pago bloqueado por presunto fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined). - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors). | | Errores de solicitud no válida | [Stripe::InvalidRequestError](https://docs.stripe.com/error-handling.md#invalid-request-errors) | 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](https://docs.stripe.com/error-handling.md#connection-errors) | Ha habido un problema de red entre tu servidor y Stripe. | | Error de API | [Stripe::APIError](https://docs.stripe.com/error-handling.md#api-errors) | Se produjo un error del lado de Stripe. (Esto no suele ocurrir). | | Error de autenticación | [Stripe::AuthenticationError](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe no puede autenticarte con la información proporcionada. | | Error de idempotencia | [Stripe::IdempotencyError](https://docs.stripe.com/error-handling.md#idempotency-errors) | Has usado una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) para una acción inesperada, como repetir una solicitud con parámetros distintos. | | Error de permiso | [Stripe::PermissionError](https://docs.stripe.com/error-handling.md#permission-errors) | La clave de API usada para esta solicitud no tiene los permisos necesarios. | | Error de límite de velocidad | [Stripe::RateLimitError](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Hiciste demasiadas llamadas API en muy poco tiempo. | | Error de verificación de firma | [Stripe::SignatureVerificationError](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) *de webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no has podido verificar que un evento de webhook sea auténtico. | ## Errores de pago 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::CardError](https://docs.stripe.com/error-handling.md#card-error). 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](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined) - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors) Para distinguir estas categorías u obtener más información sobre cómo responder, consulta el [código de error](https://docs.stripe.com/error-codes.md), el [código de rechazo](https://docs.stripe.com/declines/codes.md) y el [resultado del cargo](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Para encontrar el resultado del cargo de un objeto de error, primero debes obtener el [PaymentIntent en cuestión](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); if ($charge->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Usuarios en la versión de API [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) o anterior: (Para encontrar el resultado del cargo de un objeto de error, primero debes obtener el [PaymentIntent en cuestión](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('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](https://docs.stripe.com/testing.md#fraud-prevention) - [Simulación de pagos rechazados y otros errores de tarjeta](https://docs.stripe.com/testing.md#declined-payments) El código de prueba que figura a continuación muestra algunas posibilidades. #### Error al ejecutar - Bloqueado por presunto fraude #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Esta es una tarjeta de prueba que siempre se bloquea por supuesto fraude cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Error al ejecutar - Rechazado por el emisor #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Esta es una tarjeta de prueba que siempre rechaza el emisor cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment declined by the issuer ``` #### Error al ejecutar - Tarjeta caducada #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Esta es una tarjeta de prueba que siempre falla como caducada cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Card expired. ``` #### Error al ejecutar - Otro error de tarjeta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Esta es una tarjeta de prueba que siempre falla debido a un error de procesamiento cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Other payment error. ``` ### Pago bloqueado por presunto fraude | | | | | **Tipo** | `Stripe::CardError` | | **Códigos** | ```ruby charge = Stripe::Charge.retrieve(e.error.payment_intent.latest_charge) charge.outcome.type == 'blocked' ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **Códigos** | `e.error.payment_intent.charges.data[0].outcome.type == 'blocked'` | | **Problema** | | El sistema de prevención de fraude de Stripe, *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), 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 la integración de Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) para recopilar información más detallada. - Usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) para elementos de formularios prediseñados y optimizados. Los clientes de *Radar for Fraud Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) 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](https://docs.stripe.com/radar/risk-settings.md). (Radar for Fraud Teams) - Para cambiar los criterios de bloqueo de un pago, usa [reglas personalizadas](https://docs.stripe.com/radar/rules.md). (Radar for Fraud Teams) Puedes probar la configuración de tu integración con [tarjetas de prueba que simulan fraude](https://docs.stripe.com/radar/testing.md). Si tienes reglas de Radar personalizadas, sigue los consejos de prueba de la [documentación de Radar](https://docs.stripe.com/radar/testing.md). | ### Pago rechazado por el emisor | | | | | **Tipo** | `Stripe::CardError` | | **Códigos** | `e.error.code == "card_declined"` | | **Problema** | El 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](https://docs.stripe.com/declines/codes.md) para obtener respuestas apropiadas para cada código. También puedes: - [Sigue las recomendaciones para reducir los pagos rechazados del emisor](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) 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](https://docs.stripe.com/radar/testing.md). | ### Otros errores de pago | | | | | **Tipo** | `Stripe::CardError` | | **Problema** | Se produjo otro error de pago. | | **Soluciones** | Este 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](https://docs.stripe.com/error-codes.md) para obtener respuestas apropiadas para cada código. | ## Errores de solicitudes no válidas | | | | | **Tipo** | `Stripe::InvalidRequestError` | | **Problema** | Has hecho una llamada a la 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. - Consulta la [documentación de códigos de error](https://docs.stripe.com/error-codes.md) para obtener más información sobre el problema. - 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` | | **Problema** | Ha habido un problema de red entre tu servidor y Stripe. | | **Soluciones** | Trata el resultado de la llamada a la API como indeterminado. Es decir, no asumas que se ha llevado a cabo ni que ha fallado. 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. Para recuperarte de errores de conexión, puedes hacer lo siguiente: - Al crear o actualizar un objeto, usa una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md). Después, si se produce un error de conexión, puedes repetir la solicitud de forma segura sin riesgo de crear un segundo objeto ni de realizar la actualización dos veces. Repite la solicitud con la misma clave de idempotencia hasta que obtengas un resultado satisfactorio o de error. Para obtener consejos avanzados sobre esta estrategia, consulta [Tratamiento de errores avanzados](https://docs.stripe.com/error-low-level.md#idempotency). - Activa los [reintentos automáticos](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). 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` | | **Problema** | Se 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* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/error-low-level.md#server-errors). | ## Errores de autenticación | | | | | **Tipo** | `Stripe::AuthenticationError` | | **Problema** | Stripe no puede autenticarte con la información proporcionada. | | **Soluciones** | - Utiliza la [clave de API](https://docs.stripe.com/keys.md) correcta. - Asegúrate de no estar usando una clave que hayas [«rotado» o anulado](https://docs.stripe.com/keys.md#rolling-keys). | ## Errores de idempotencia | | | | | **Tipo** | `Stripe::IdempotencyError` | | **Problema** | Has usado una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) 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. | ## Errores de permisos | | | | | **Tipo** | `Stripe::PermissionError` | | **Problema** | La clave de API usada para esta solicitud no tiene los permisos necesarios. | | **Soluciones** | - Asegúrate de no estar usando una [clave de API restringida](https://docs.stripe.com/keys-best-practices.md#limit-access) para un servicio al que no tienes acceso. - No realices acciones en el Dashboard si has iniciado sesión con una [función de usuario](https://docs.stripe.com/get-started/account/teams/roles.md) que no tenga permiso. | ## Errores de límite de velocidad | | | | | **Tipo** | `Stripe::RateLimitError` | | **Problema** | Has 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](https://docs.stripe.com/rate-limits.md) 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](https://support.stripe.com/) por adelantado. | ## Errores de verificación de firma | | | | | **Tipo** | `Stripe::SignatureVerificationError` | | **Problema** | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) *de webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no has podido 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 cuando no deberías, por ejemplo, con webhooks que sabes que se originan en Stripe, consulta la documentación sobre [verificación de firma de webhook](https://docs.stripe.com/webhooks.md#verify-events) para obtener más consejos. En concreto, asegúrate de usar el secreto del punto de conexión correcto. Es diferente de la clave de API. | En la biblioteca de Python de Stripe, los objetos de error pertenecen a `stripe.StripeError` y sus subclases. Utiliza la documentación de cada clase para obtener consejos sobre cómo responder. | Nombre | Clase | Descripción | | ------------------------------ | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Error de pago | [stripe.CardError](https://docs.stripe.com/error-handling.md#payment-errors) | Se ha producido un error durante un pago debido a alguno de estos motivos: - [Pago bloqueado por presunto fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined). - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors). | | Errores de solicitud no válida | [stripe.InvalidRequestError](https://docs.stripe.com/error-handling.md#invalid-request-errors) | 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](https://docs.stripe.com/error-handling.md#connection-errors) | Ha habido un problema de red entre tu servidor y Stripe. | | Error de API | [stripe.APIError](https://docs.stripe.com/error-handling.md#api-errors) | Se produjo un error del lado de Stripe. (Esto no suele ocurrir). | | Error de autenticación | [stripe.AuthenticationError](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe no puede autenticarte con la información proporcionada. | | Error de idempotencia | [stripe.IdempotencyError](https://docs.stripe.com/error-handling.md#idempotency-errors) | Has usado una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) para una acción inesperada, como repetir una solicitud con parámetros distintos. | | Error de permiso | [stripe.PermissionError](https://docs.stripe.com/error-handling.md#permission-errors) | La clave de API usada para esta solicitud no tiene los permisos necesarios. | | Error de límite de velocidad | [stripe.RateLimitError](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Hiciste demasiadas llamadas API en muy poco tiempo. | | Error de verificación de firma | [stripe.SignatureVerificationError](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) *de webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no has podido verificar que un evento de webhook sea auténtico. | ## Errores de pago 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. CardError](https://docs.stripe.com/error-handling.md#card-error). 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](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined) - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors) Para distinguir estas categorías u obtener más información sobre cómo responder, consulta el [código de error](https://docs.stripe.com/error-codes.md), el [código de rechazo](https://docs.stripe.com/declines/codes.md) y el [resultado del cargo](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Para encontrar el resultado del cargo de un objeto de error, primero debes obtener el [PaymentIntent en cuestión](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); if ($charge->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Usuarios en la versión de API [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) o anterior: (Para encontrar el resultado del cargo de un objeto de error, primero debes obtener el [PaymentIntent en cuestión](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('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](https://docs.stripe.com/testing.md#fraud-prevention) - [Simulación de pagos rechazados y otros errores de tarjeta](https://docs.stripe.com/testing.md#declined-payments) El código de prueba que figura a continuación muestra algunas posibilidades. #### Error al ejecutar - Bloqueado por presunto fraude #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Esta es una tarjeta de prueba que siempre se bloquea por supuesto fraude cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Error al ejecutar - Rechazado por el emisor #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Esta es una tarjeta de prueba que siempre rechaza el emisor cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment declined by the issuer ``` #### Error al ejecutar - Tarjeta caducada #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Esta es una tarjeta de prueba que siempre falla como caducada cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Card expired. ``` #### Error al ejecutar - Otro error de tarjeta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Esta es una tarjeta de prueba que siempre falla debido a un error de procesamiento cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Other payment error. ``` ### Pago bloqueado por presunto fraude | | | | | **Tipo** | `stripe.CardError` | | **Códigos** | ```python charge = stripe.Charge.retrieve(e.error.payment_intent.latest_charge) charge.outcome.type == 'blocked' ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **Códigos** | `e.error.payment_intent.charges.data[0].outcome.type == 'blocked'` | | **Problema** | | El sistema de prevención de fraude de Stripe, *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), 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 la integración de Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) para recopilar información más detallada. - Usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) para elementos de formularios prediseñados y optimizados. Los clientes de *Radar for Fraud Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) 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](https://docs.stripe.com/radar/risk-settings.md). (Radar for Fraud Teams) - Para cambiar los criterios de bloqueo de un pago, usa [reglas personalizadas](https://docs.stripe.com/radar/rules.md). (Radar for Fraud Teams) Puedes probar la configuración de tu integración con [tarjetas de prueba que simulan fraude](https://docs.stripe.com/radar/testing.md). Si tienes reglas de Radar personalizadas, sigue los consejos de prueba de la [documentación de Radar](https://docs.stripe.com/radar/testing.md). | ### Pago rechazado por el emisor | | | | | **Tipo** | `stripe.CardError` | | **Códigos** | `e.code == "card_declined"` | | **Problema** | El 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](https://docs.stripe.com/declines/codes.md) para obtener respuestas apropiadas para cada código. También puedes: - [Sigue las recomendaciones para reducir los pagos rechazados del emisor](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) 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](https://docs.stripe.com/radar/testing.md). | ### Otros errores de pago | | | | | **Tipo** | `stripe.CardError` | | **Problema** | Se produjo otro error de pago. | | **Soluciones** | Este 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](https://docs.stripe.com/error-codes.md) para obtener respuestas apropiadas para cada código. | ## Errores de solicitudes no válidas | | | | | **Tipo** | `stripe.InvalidRequestError` | | **Problema** | Has hecho una llamada a la 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. - Consulta la [documentación de códigos de error](https://docs.stripe.com/error-codes.md) para obtener más información sobre el problema. - Para mayor comodidad, puedes acceder al 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 cuál. | ## Errores de conexión | | | | | **Tipo** | `stripe.APIConnectionError` | | **Problema** | Ha habido un problema de red entre tu servidor y Stripe. | | **Soluciones** | Trata el resultado de la llamada a la API como indeterminado. Es decir, no asumas que se ha llevado a cabo ni que ha fallado. 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. Para recuperarte de errores de conexión, puedes hacer lo siguiente: - Al crear o actualizar un objeto, usa una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md). Después, si se produce un error de conexión, puedes repetir la solicitud de forma segura sin riesgo de crear un segundo objeto ni de realizar la actualización dos veces. Repite la solicitud con la misma clave de idempotencia hasta que obtengas un resultado satisfactorio o de error. Para obtener consejos avanzados sobre esta estrategia, consulta [Tratamiento de errores avanzados](https://docs.stripe.com/error-low-level.md#idempotency). - Activa los [reintentos automáticos](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). 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` | | **Problema** | Se 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* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/error-low-level.md#server-errors). | ## Errores de autenticación | | | | | **Tipo** | `stripe.AuthenticationError` | | **Problema** | Stripe no puede autenticarte con la información proporcionada. | | **Soluciones** | - Utiliza la [clave de API](https://docs.stripe.com/keys.md) correcta. - Asegúrate de no estar usando una clave que hayas [«rotado» o anulado](https://docs.stripe.com/keys.md#rolling-keys). | ## Errores de idempotencia | | | | | **Tipo** | `stripe.IdempotencyError` | | **Problema** | Has usado una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) 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. | ## Errores de permisos | | | | | **Tipo** | `stripe.PermissionError` | | **Problema** | La clave de API usada para esta solicitud no tiene los permisos necesarios. | | **Soluciones** | - Asegúrate de no estar usando una [clave de API restringida](https://docs.stripe.com/keys-best-practices.md#limit-access) para un servicio al que no tienes acceso. - No realices acciones en el Dashboard si has iniciado sesión con una [función de usuario](https://docs.stripe.com/get-started/account/teams/roles.md) que no tenga permiso. | ## Errores de límite de velocidad | | | | | **Tipo** | `stripe.RateLimitError` | | **Problema** | Has 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](https://docs.stripe.com/rate-limits.md) 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](https://support.stripe.com/) por adelantado. | ## Errores de verificación de firma | | | | | **Tipo** | `stripe.SignatureVerificationError` | | **Problema** | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) *de webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no has podido 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 cuando no deberías, por ejemplo, con webhooks que sabes que se originan en Stripe, consulta la documentación sobre [verificación de firma de webhook](https://docs.stripe.com/webhooks.md#verify-events) para obtener más consejos. En concreto, asegúrate de usar el secreto del punto de conexión correcto. Es diferente de la clave de API. | En la biblioteca de PHP de Stripe, cada tipo de error tiene su propia clase. Utiliza la documentación de cada clase para ver consejos sobre cómo responder. | Nombre | Clase | Descripción | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Error de pago | [Stripe\Exception\CardException](https://docs.stripe.com/error-handling.md#payment-errors) | Se ha producido un error durante un pago debido a alguno de estos motivos: - [Pago bloqueado por presunto fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined). - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors). | | Errores de solicitud no válida | [Stripe\Exception\InvalidRequestException](https://docs.stripe.com/error-handling.md#invalid-request-errors) | 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\Exception\ApiConnectionException](https://docs.stripe.com/error-handling.md#connection-errors) | Ha habido un problema de red entre tu servidor y Stripe. | | Error de API | [Stripe\Exception\ApiErrorException](https://docs.stripe.com/error-handling.md#api-errors) | Se produjo un error del lado de Stripe. (Esto no suele ocurrir). | | Error de autenticación | [Stripe\Exception\AuthenticationException](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe no puede autenticarte con la información proporcionada. | | Error de idempotencia | [Stripe\Exception\IdempotencyException](https://docs.stripe.com/error-handling.md#idempotency-errors) | Has usado una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) para una acción inesperada, como repetir una solicitud con parámetros distintos. | | Error de permiso | [Stripe\Exception\PermissionException](https://docs.stripe.com/error-handling.md#permission-errors) | La clave de API usada para esta solicitud no tiene los permisos necesarios. | | Error de límite de velocidad | [Stripe\Exception\RateLimitException](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Hiciste demasiadas llamadas API en muy poco tiempo. | | Error de verificación de firma | [Stripe\Exception\SignatureVerificationException](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) *de webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no has podido verificar que un evento de webhook sea auténtico. | ## Errores de pago 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\Exception\CardException](https://docs.stripe.com/error-handling.md#card-error). 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](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined) - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors) Para distinguir estas categorías u obtener más información sobre cómo responder, consulta el [código de error](https://docs.stripe.com/error-codes.md), el [código de rechazo](https://docs.stripe.com/declines/codes.md) y el [resultado del cargo](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Para encontrar el resultado del cargo de un objeto de error, primero debes obtener el [PaymentIntent en cuestión](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); if ($charge->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Usuarios en la versión de API [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) o anterior: (Para encontrar el resultado del cargo de un objeto de error, primero debes obtener el [PaymentIntent en cuestión](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('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](https://docs.stripe.com/testing.md#fraud-prevention) - [Simulación de pagos rechazados y otros errores de tarjeta](https://docs.stripe.com/testing.md#declined-payments) El código de prueba que figura a continuación muestra algunas posibilidades. #### Error al ejecutar - Bloqueado por presunto fraude #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Esta es una tarjeta de prueba que siempre se bloquea por supuesto fraude cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Error al ejecutar - Rechazado por el emisor #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Esta es una tarjeta de prueba que siempre rechaza el emisor cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment declined by the issuer ``` #### Error al ejecutar - Tarjeta caducada #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Esta es una tarjeta de prueba que siempre falla como caducada cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Card expired. ``` #### Error al ejecutar - Otro error de tarjeta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Esta es una tarjeta de prueba que siempre falla debido a un error de procesamiento cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Other payment error. ``` ### Pago bloqueado por presunto fraude | | | | | **Tipo** | `Stripe\Exception\CardException` | | **Códigos** | ```php $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); $charge->outcome->type == 'blocked' ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **Códigos** | `$e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked'` | | **Problema** | | El sistema de prevención de fraude de Stripe, *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), 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 la integración de Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) para recopilar información más detallada. - Usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) para elementos de formularios prediseñados y optimizados. Los clientes de *Radar for Fraud Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) 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](https://docs.stripe.com/radar/risk-settings.md). (Radar for Fraud Teams) - Para cambiar los criterios de bloqueo de un pago, usa [reglas personalizadas](https://docs.stripe.com/radar/rules.md). (Radar for Fraud Teams) Puedes probar la configuración de tu integración con [tarjetas de prueba que simulan fraude](https://docs.stripe.com/radar/testing.md). Si tienes reglas de Radar personalizadas, sigue los consejos de prueba de la [documentación de Radar](https://docs.stripe.com/radar/testing.md). | ### Pago rechazado por el emisor | | | | | **Tipo** | `Stripe\Exception\CardException` | | **Códigos** | `$e->getError()->code == "card_declined"` | | **Problema** | El 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](https://docs.stripe.com/declines/codes.md) para obtener respuestas apropiadas para cada código. También puedes: - [Sigue las recomendaciones para reducir los pagos rechazados del emisor](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) 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](https://docs.stripe.com/radar/testing.md). | ### Otros errores de pago | | | | | **Tipo** | `Stripe\Exception\CardException` | | **Problema** | Se produjo otro error de pago. | | **Soluciones** | Este 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](https://docs.stripe.com/error-codes.md) para obtener respuestas apropiadas para cada código. | ## Errores de solicitudes no válidas | | | | | **Tipo** | `Stripe\Exception\InvalidRequestException` | | **Problema** | Has hecho una llamada a la 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. - Consulta la [documentación de códigos de error](https://docs.stripe.com/error-codes.md) para obtener más información sobre el problema. - Para mayor comodidad, puedes acceder al enlace `e->getError()->doc_url` para ver la documentación sobre el código de error. - Si el error involucra un parámetro específico, usa `e->getError()->param` para determinar cuál. | ## Errores de conexión | | | | | **Tipo** | `Stripe\Exception\ApiConnectionException` | | **Problema** | Ha habido un problema de red entre tu servidor y Stripe. | | **Soluciones** | Trata el resultado de la llamada a la API como indeterminado. Es decir, no asumas que se ha llevado a cabo ni que ha fallado. 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. Para recuperarte de errores de conexión, puedes hacer lo siguiente: - Al crear o actualizar un objeto, usa una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md). Después, si se produce un error de conexión, puedes repetir la solicitud de forma segura sin riesgo de crear un segundo objeto ni de realizar la actualización dos veces. Repite la solicitud con la misma clave de idempotencia hasta que obtengas un resultado satisfactorio o de error. Para obtener consejos avanzados sobre esta estrategia, consulta [Tratamiento de errores avanzados](https://docs.stripe.com/error-low-level.md#idempotency). - Activa los [reintentos automáticos](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). 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\Exception\APIException` | | **Problema** | Se 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* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/error-low-level.md#server-errors). | ## Errores de autenticación | | | | | **Tipo** | `Stripe\Exception\AuthenticationException` | | **Problema** | Stripe no puede autenticarte con la información proporcionada. | | **Soluciones** | - Utiliza la [clave de API](https://docs.stripe.com/keys.md) correcta. - Asegúrate de no estar usando una clave que hayas [«rotado» o anulado](https://docs.stripe.com/keys.md#rolling-keys). | ## Errores de idempotencia | | | | | **Tipo** | `Stripe\Exception\IdempotencyException` | | **Problema** | Has usado una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) 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. | ## Errores de permisos | | | | | **Tipo** | `Stripe\Exception\PermissionException` | | **Problema** | La clave de API usada para esta solicitud no tiene los permisos necesarios. | | **Soluciones** | - Asegúrate de no estar usando una [clave de API restringida](https://docs.stripe.com/keys-best-practices.md#limit-access) para un servicio al que no tienes acceso. - No realices acciones en el Dashboard si has iniciado sesión con una [función de usuario](https://docs.stripe.com/get-started/account/teams/roles.md) que no tenga permiso. | ## Errores de límite de velocidad | | | | | **Tipo** | `Stripe\Exception\RateLimitException` | | **Problema** | Has 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](https://docs.stripe.com/rate-limits.md) 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](https://support.stripe.com/) por adelantado. | ## Errores de verificación de firma | | | | | **Tipo** | `Stripe\Exception\SignatureVerificationException` | | **Problema** | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) *de webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no has podido 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 cuando no deberías, por ejemplo, con webhooks que sabes que se originan en Stripe, consulta la documentación sobre [verificación de firma de webhook](https://docs.stripe.com/webhooks.md#verify-events) para obtener más consejos. En concreto, asegúrate de usar el secreto del punto de conexión correcto. Es diferente de la clave de API. | En la biblioteca de Java de Stripe, cada tipo de error tiene su propia clase. Utiliza la documentación de cada clase para ver consejos sobre cómo responder. | Nombre | Clase | Descripción | | ------------------------------ | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Error de pago | [CardException](https://docs.stripe.com/error-handling.md#payment-errors) | Se ha producido un error durante un pago debido a alguno de estos motivos: - [Pago bloqueado por presunto fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined). - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors). | | Errores de solicitud no válida | [InvalidRequestException](https://docs.stripe.com/error-handling.md#invalid-request-errors) | 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 | [ApiConnectionException](https://docs.stripe.com/error-handling.md#connection-errors) | Ha habido un problema de red entre tu servidor y Stripe. | | Error de API | [APIException](https://docs.stripe.com/error-handling.md#api-errors) | Se produjo un error del lado de Stripe. (Esto no suele ocurrir). | | Error de autenticación | [AuthenticationException](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe no puede autenticarte con la información proporcionada. | | Error de idempotencia | [IdempotencyException](https://docs.stripe.com/error-handling.md#idempotency-errors) | Has usado una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) para una acción inesperada, como repetir una solicitud con parámetros distintos. | | Error de permiso | [PermissionException](https://docs.stripe.com/error-handling.md#permission-errors) | La clave de API usada para esta solicitud no tiene los permisos necesarios. | | Error de límite de velocidad | [RateLimitException](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Hiciste demasiadas llamadas API en muy poco tiempo. | | Error de verificación de firma | [SignatureVerificationException](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) *de webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no has podido verificar que un evento de webhook sea auténtico. | ## Errores de pago 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 [CardException](https://docs.stripe.com/error-handling.md#card-error). 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](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined) - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors) Para distinguir estas categorías u obtener más información sobre cómo responder, consulta el [código de error](https://docs.stripe.com/error-codes.md), el [código de rechazo](https://docs.stripe.com/declines/codes.md) y el [resultado del cargo](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Para encontrar el resultado del cargo de un objeto de error, primero debes obtener el [PaymentIntent en cuestión](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); if ($charge->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Usuarios en la versión de API [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) o anterior: (Para encontrar el resultado del cargo de un objeto de error, primero debes obtener el [PaymentIntent en cuestión](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('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](https://docs.stripe.com/testing.md#fraud-prevention) - [Simulación de pagos rechazados y otros errores de tarjeta](https://docs.stripe.com/testing.md#declined-payments) El código de prueba que figura a continuación muestra algunas posibilidades. #### Error al ejecutar - Bloqueado por presunto fraude #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Esta es una tarjeta de prueba que siempre se bloquea por supuesto fraude cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Error al ejecutar - Rechazado por el emisor #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Esta es una tarjeta de prueba que siempre rechaza el emisor cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment declined by the issuer ``` #### Error al ejecutar - Tarjeta caducada #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Esta es una tarjeta de prueba que siempre falla como caducada cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Card expired. ``` #### Error al ejecutar - Otro error de tarjeta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Esta es una tarjeta de prueba que siempre falla debido a un error de procesamiento cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Other payment error. ``` ### Pago bloqueado por presunto fraude | | | | | **Tipo** | `CardException` | | **Códigos** | ```java Charge charge = Charge.retrieve(ex.getStripeError() .getPaymentIntent() .getLatestCharge()); charge.getOutcome().getType() == "blocked" ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **Códigos** | `ex.getStripeError().getPaymentIntent().getCharges().getData().get(0).getOutcome().getType() == "blocked"` | | **Problema** | | El sistema de prevención de fraude de Stripe, *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), 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 la integración de Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) para recopilar información más detallada. - Usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) para elementos de formularios prediseñados y optimizados. Los clientes de *Radar for Fraud Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) 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](https://docs.stripe.com/radar/risk-settings.md). (Radar for Fraud Teams) - Para cambiar los criterios de bloqueo de un pago, usa [reglas personalizadas](https://docs.stripe.com/radar/rules.md). (Radar for Fraud Teams) Puedes probar la configuración de tu integración con [tarjetas de prueba que simulan fraude](https://docs.stripe.com/radar/testing.md). Si tienes reglas de Radar personalizadas, sigue los consejos de prueba de la [documentación de Radar](https://docs.stripe.com/radar/testing.md). | ### Pago rechazado por el emisor | | | | | **Tipo** | `CardException` | | **Códigos** | `e.getCode() == "card_declined"` | | **Problema** | El 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](https://docs.stripe.com/declines/codes.md) para obtener respuestas apropiadas para cada código. También puedes: - [Sigue las recomendaciones para reducir los pagos rechazados del emisor](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) 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](https://docs.stripe.com/radar/testing.md). | ### Otros errores de pago | | | | | **Tipo** | `CardException` | | **Problema** | Se produjo otro error de pago. | | **Soluciones** | Este 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](https://docs.stripe.com/error-codes.md) para obtener respuestas apropiadas para cada código. | ## Errores de solicitudes no válidas | | | | | **Tipo** | `InvalidRequestException` | | **Problema** | Has hecho una llamada a la 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. - Consulta la [documentación de códigos de error](https://docs.stripe.com/error-codes.md) para obtener más información sobre el problema. - Para mayor comodidad, puedes acceder al 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 cuál. | ## Errores de conexión | | | | | **Tipo** | `APIConnectionException` | | **Problema** | Ha habido un problema de red entre tu servidor y Stripe. | | **Soluciones** | Trata el resultado de la llamada a la API como indeterminado. Es decir, no asumas que se ha llevado a cabo ni que ha fallado. 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. Para recuperarte de errores de conexión, puedes hacer lo siguiente: - Al crear o actualizar un objeto, usa una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md). Después, si se produce un error de conexión, puedes repetir la solicitud de forma segura sin riesgo de crear un segundo objeto ni de realizar la actualización dos veces. Repite la solicitud con la misma clave de idempotencia hasta que obtengas un resultado satisfactorio o de error. Para obtener consejos avanzados sobre esta estrategia, consulta [Tratamiento de errores avanzados](https://docs.stripe.com/error-low-level.md#idempotency). - Activa los [reintentos automáticos](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). 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** | `APIException` | | **Problema** | Se 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* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/error-low-level.md#server-errors). | ## Errores de autenticación | | | | | **Tipo** | `AuthenticationException` | | **Problema** | Stripe no puede autenticarte con la información proporcionada. | | **Soluciones** | - Utiliza la [clave de API](https://docs.stripe.com/keys.md) correcta. - Asegúrate de no estar usando una clave que hayas [«rotado» o anulado](https://docs.stripe.com/keys.md#rolling-keys). | ## Errores de idempotencia | | | | | **Tipo** | `IdempotencyException` | | **Problema** | Has usado una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) 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. | ## Errores de permisos | | | | | **Tipo** | `PermissionException` | | **Problema** | La clave de API usada para esta solicitud no tiene los permisos necesarios. | | **Soluciones** | - Asegúrate de no estar usando una [clave de API restringida](https://docs.stripe.com/keys-best-practices.md#limit-access) para un servicio al que no tienes acceso. - No realices acciones en el Dashboard si has iniciado sesión con una [función de usuario](https://docs.stripe.com/get-started/account/teams/roles.md) que no tenga permiso. | ## Errores de límite de velocidad | | | | | **Tipo** | `RateLimitException` | | **Problema** | Has 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](https://docs.stripe.com/rate-limits.md) 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](https://support.stripe.com/) por adelantado. | ## Errores de verificación de firma | | | | | **Tipo** | `SignatureVerificationException` | | **Problema** | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) *de webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no has podido 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 cuando no deberías, por ejemplo, con webhooks que sabes que se originan en Stripe, consulta la documentación sobre [verificación de firma de webhook](https://docs.stripe.com/webhooks.md#verify-events) para obtener más consejos. En concreto, asegúrate de usar el secreto del punto de conexión correcto. Es diferente de la clave de API. | En la biblioteca de Node.js 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 | [StripeCardError](https://docs.stripe.com/error-handling.md#payment-errors) | Se ha producido un error durante un pago debido a alguno de estos motivos: - [Pago bloqueado por presunto fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined). - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors). | | Errores de solicitud no válida | [StripeInvalidRequestError](https://docs.stripe.com/error-handling.md#invalid-request-errors) | 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 | [StripeConnectionError](https://docs.stripe.com/error-handling.md#connection-errors) | Ha habido un problema de red entre tu servidor y Stripe. | | Error de API | [StripeAPIError](https://docs.stripe.com/error-handling.md#api-errors) | Se produjo un error del lado de Stripe. (Esto no suele ocurrir). | | Error de autenticación | [StripeAuthenticationError](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe no puede autenticarte con la información proporcionada. | | Error de idempotencia | [StripeIdempotencyError](https://docs.stripe.com/error-handling.md#idempotency-errors) | Has usado una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) para una acción inesperada, como repetir una solicitud con parámetros distintos. | | Error de permiso | [StripePermissionError](https://docs.stripe.com/error-handling.md#permission-errors) | La clave de API usada para esta solicitud no tiene los permisos necesarios. | | Error de límite de velocidad | [StripeRateLimitError](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Hiciste demasiadas llamadas API en muy poco tiempo. | | Error de verificación de firma | [StripeSignatureVerificationError](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) *de webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no has podido verificar que un evento de webhook sea auténtico. | ## Errores de pago 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 [StripeCardError](https://docs.stripe.com/error-handling.md#card-error). 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](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined) - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors) Para distinguir estas categorías u obtener más información sobre cómo responder, consulta el [código de error](https://docs.stripe.com/error-codes.md), el [código de rechazo](https://docs.stripe.com/declines/codes.md) y el [resultado del cargo](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Para encontrar el resultado del cargo de un objeto de error, primero debes obtener el [PaymentIntent en cuestión](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); if ($charge->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Usuarios en la versión de API [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) o anterior: (Para encontrar el resultado del cargo de un objeto de error, primero debes obtener el [PaymentIntent en cuestión](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('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](https://docs.stripe.com/testing.md#fraud-prevention) - [Simulación de pagos rechazados y otros errores de tarjeta](https://docs.stripe.com/testing.md#declined-payments) El código de prueba que figura a continuación muestra algunas posibilidades. #### Error al ejecutar - Bloqueado por presunto fraude #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Esta es una tarjeta de prueba que siempre se bloquea por supuesto fraude cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Error al ejecutar - Rechazado por el emisor #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Esta es una tarjeta de prueba que siempre rechaza el emisor cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment declined by the issuer ``` #### Error al ejecutar - Tarjeta caducada #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Esta es una tarjeta de prueba que siempre falla como caducada cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Card expired. ``` #### Error al ejecutar - Otro error de tarjeta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Esta es una tarjeta de prueba que siempre falla debido a un error de procesamiento cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Other payment error. ``` ### Pago bloqueado por presunto fraude | | | | | **Tipo** | `StripeCardError` | | **Códigos** | ```javascript const charge = await stripe.charges.retrieve(e.payment_intent.latest_charge) charge.outcome.type === 'blocked' ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **Códigos** | `e.payment_intent.charges.data[0].outcome.type === 'blocked'` | | **Problema** | | El sistema de prevención de fraude de Stripe, *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), 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 la integración de Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) para recopilar información más detallada. - Usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) para elementos de formularios prediseñados y optimizados. Los clientes de *Radar for Fraud Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) 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](https://docs.stripe.com/radar/risk-settings.md). (Radar for Fraud Teams) - Para cambiar los criterios de bloqueo de un pago, usa [reglas personalizadas](https://docs.stripe.com/radar/rules.md). (Radar for Fraud Teams) Puedes probar la configuración de tu integración con [tarjetas de prueba que simulan fraude](https://docs.stripe.com/radar/testing.md). Si tienes reglas de Radar personalizadas, sigue los consejos de prueba de la [documentación de Radar](https://docs.stripe.com/radar/testing.md). | ### Pago rechazado por el emisor | | | | | **Tipo** | `StripeCardError` | | **Códigos** | `e.code === 'card_declined'` | | **Problema** | El 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](https://docs.stripe.com/declines/codes.md) para obtener respuestas apropiadas para cada código. También puedes: - [Sigue las recomendaciones para reducir los pagos rechazados del emisor](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) 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](https://docs.stripe.com/radar/testing.md). | ### Otros errores de pago | | | | | **Tipo** | `StripeCardError` | | **Problema** | Se produjo otro error de pago. | | **Soluciones** | Este 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](https://docs.stripe.com/error-codes.md) para obtener respuestas apropiadas para cada código. | ## Errores de solicitudes no válidas | | | | | **Tipo** | `StripeInvalidRequestError` | | **Problema** | Has hecho una llamada a la 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. - Consulta la [documentación de códigos de error](https://docs.stripe.com/error-codes.md) para obtener más información sobre el problema. - Para mayor comodidad, puedes acceder al 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 cuál. | ## Errores de conexión | | | | | **Tipo** | `StripeAPIConnectionError` | | **Problema** | Ha habido un problema de red entre tu servidor y Stripe. | | **Soluciones** | Trata el resultado de la llamada a la API como indeterminado. Es decir, no asumas que se ha llevado a cabo ni que ha fallado. 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. Para recuperarte de errores de conexión, puedes hacer lo siguiente: - Al crear o actualizar un objeto, usa una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md). Después, si se produce un error de conexión, puedes repetir la solicitud de forma segura sin riesgo de crear un segundo objeto ni de realizar la actualización dos veces. Repite la solicitud con la misma clave de idempotencia hasta que obtengas un resultado satisfactorio o de error. Para obtener consejos avanzados sobre esta estrategia, consulta [Tratamiento de errores avanzados](https://docs.stripe.com/error-low-level.md#idempotency). - Activa los [reintentos automáticos](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). 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** | `StripeAPIError` | | **Problema** | Se 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* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/error-low-level.md#server-errors). | ## Errores de autenticación | | | | | **Tipo** | `StripeAuthenticationError` | | **Problema** | Stripe no puede autenticarte con la información proporcionada. | | **Soluciones** | - Utiliza la [clave de API](https://docs.stripe.com/keys.md) correcta. - Asegúrate de no estar usando una clave que hayas [«rotado» o anulado](https://docs.stripe.com/keys.md#rolling-keys). | ## Errores de idempotencia | | | | | **Tipo** | `StripeIdempotencyError` | | **Problema** | Has usado una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) 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. | ## Errores de permisos | | | | | **Tipo** | `StripePermissionError` | | **Problema** | La clave de API usada para esta solicitud no tiene los permisos necesarios. | | **Soluciones** | - Asegúrate de no estar usando una [clave de API restringida](https://docs.stripe.com/keys-best-practices.md#limit-access) para un servicio al que no tienes acceso. - No realices acciones en el Dashboard si has iniciado sesión con una [función de usuario](https://docs.stripe.com/get-started/account/teams/roles.md) que no tenga permiso. | ## Errores de límite de velocidad | | | | | **Tipo** | `StripeRateLimitError` | | **Problema** | Has 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](https://docs.stripe.com/rate-limits.md) 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](https://support.stripe.com/) por adelantado. | ## Errores de verificación de firma | | | | | **Tipo** | `StripeSignatureVerificationError` | | **Problema** | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) *de webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no has podido 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 cuando no deberías, por ejemplo, con webhooks que sabes que se originan en Stripe, consulta la documentación sobre [verificación de firma de webhook](https://docs.stripe.com/webhooks.md#verify-events) para obtener más consejos. En concreto, asegúrate de usar el secreto del punto de conexión correcto. Es diferente de la clave de API. | 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](https://docs.stripe.com/error-handling.md#payment-errors) | Se ha producido un error durante un pago debido a alguno de estos motivos: - [Pago bloqueado por presunto fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined). - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors). | | Errores de solicitud no válida | [stripe.ErrorTypeInvalidRequest](https://docs.stripe.com/error-handling.md#invalid-request-errors) | 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](https://docs.stripe.com/error-handling.md#rate-limiting) - [Error de autenticación](https://docs.stripe.com/error-handling.md#authentication-errors) - [Estado o parámetro no válido](https://docs.stripe.com/error-handling.md#invalid-parameters-or-state) | | Error de API | [stripe.ErrorTypeAPI](https://docs.stripe.com/error-handling.md#api-errors) | Se produjo un error del lado de Stripe. (Esto no suele ocurrir). | | Error de idempotencia | [stripe.ErrorTypeIdempotency](https://docs.stripe.com/error-handling.md#idempotency-errors) | Has usado una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) para una acción inesperada, como repetir una solicitud con parámetros distintos. | ## Errores de tarjetas 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](https://docs.stripe.com/error-handling.md#card-error). 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](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined) - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors) Para distinguir estas categorías u obtener más información sobre cómo responder, consulta el [código de error](https://docs.stripe.com/error-codes.md), el [código de rechazo](https://docs.stripe.com/declines/codes.md) y el [resultado del cargo](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Para encontrar el resultado del cargo de un objeto de error, primero debes obtener el [PaymentIntent en cuestión](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); if ($charge->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Usuarios en la versión de API [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) o anterior: (Para encontrar el resultado del cargo de un objeto de error, primero debes obtener el [PaymentIntent en cuestión](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('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](https://docs.stripe.com/testing.md#fraud-prevention) - [Simulación de pagos rechazados y otros errores de tarjeta](https://docs.stripe.com/testing.md#declined-payments) El código de prueba que figura a continuación muestra algunas posibilidades. #### Error al ejecutar - Bloqueado por presunto fraude #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Esta es una tarjeta de prueba que siempre se bloquea por supuesto fraude cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Error al ejecutar - Rechazado por el emisor #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Esta es una tarjeta de prueba que siempre rechaza el emisor cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment declined by the issuer ``` #### Error al ejecutar - Tarjeta caducada #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Esta es una tarjeta de prueba que siempre falla como caducada cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Card expired. ``` #### Error al ejecutar - Otro error de tarjeta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Esta es una tarjeta de prueba que siempre falla debido a un error de procesamiento cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Other payment error. ``` ### Bloqueado por presunto fraude | | | | | **Tipo** | `stripe.ErrorTypeCard` | | **Códigos** | ```go charge = Charge.retrieve(stripeErr.PaymentIntent.LatestCharge) charge.Outcome.Type == "blocked" ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **Códigos** | `stripeErr.PaymentIntent.Charges.Data[0].Outcome.Type == "blocked"` | | **Problema** | | El sistema de prevención de fraude de Stripe, *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), 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 la integración de Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) para recopilar información más detallada. - Usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) para elementos de formularios prediseñados y optimizados. Los clientes de *Radar for Fraud Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) 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](https://docs.stripe.com/radar/risk-settings.md). (Radar for Fraud Teams) - Para cambiar los criterios de bloqueo de un pago, usa [reglas personalizadas](https://docs.stripe.com/radar/rules.md). (Radar for Fraud Teams) Puedes probar la configuración de tu integración con [tarjetas de prueba que simulan fraude](https://docs.stripe.com/radar/testing.md). Si tienes reglas de Radar personalizadas, sigue los consejos de prueba de la [documentación de Radar](https://docs.stripe.com/radar/testing.md). | ### Rechazado por el emisor | | | | | **Tipo** | `stripe.ErrorTypeCard` | | **Códigos** | `cardErr.Error.Code == stripe.ErrorCodeCardDeclined` | | **Problema** | El 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](https://docs.stripe.com/declines/codes.md) para obtener respuestas apropiadas para cada código. También puedes: - [Sigue las recomendaciones para reducir los pagos rechazados del emisor](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) 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](https://docs.stripe.com/radar/testing.md). | ### Otros errores de pago | | | | | **Tipo** | `stripe.ErrorTypeCard` | | **Problema** | Se produjo otro error de pago. | | **Soluciones** | Este 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](https://docs.stripe.com/error-codes.md) 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](https://docs.stripe.com/error-codes.md) 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](https://docs.stripe.com/error-handling.md#rate-limit-errors) - `secret_key_required` refleja un [error de autenticación](https://docs.stripe.com/error-handling.md#authentication-errors) - Otros códigos de error reflejan [parámetros o estados no válidos](https://docs.stripe.com/error-handling.md#other-invalid-request-errors) ### Errores de límite de velocidad | | | | | **Tipo** | `stripe.ErrorTypeInvalidRequest` | | **Códigos** | `stripeErr.Code == stripe.ErrorCodeRateLimit or stripeErr.Code == stripe.ErrorCodeLockTimeout` | | **Problema** | Has 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](https://docs.stripe.com/rate-limits.md) 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](https://support.stripe.com/) por adelantado. | ### Errores de autenticación | | | | | **Tipo** | `stripe.ErrorTypeInvalidRequest` | | **Códigos** | `stripeErr.Code == stripe.ErrorCodeSecretKeyRequired` | | **Problema** | Stripe no puede autenticarte con la información proporcionada. | | **Soluciones** | - Utiliza la [clave de API](https://docs.stripe.com/keys.md) correcta. - Asegúrate de no estar usando una clave que hayas [«rotado» o anulado](https://docs.stripe.com/keys.md#rolling-keys). | ### Estado o parámetro inválido | | | | | **Tipo** | `stripe.ErrorTypeInvalidRequest` | | **Códigos** | `stripeErr.Code != stripe.ErrorCodeRateLimit and stripeErr.Code != stripe.ErrorCodeLockTimeout and stripeErr.Code != stripe.ErrorCodeSecretKeyRequired` | | **Problema** | Has hecho una llamada a la 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. - Consulta la [documentación de códigos de error](https://docs.stripe.com/error-codes.md) 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` | | **Problema** | Se 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* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/error-low-level.md#server-errors). | ## Errores de idempotencia | | | | | **Tipo** | `stripe.ErrorTypeIdempotency` | | **Problema** | Has usado una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) 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. | En la biblioteca de .NET de Stripe, cada objeto de error tiene un atributo `type`. Utiliza la documentación de cada clase para ver consejos sobre cómo responder. | Nombre | Tipo | Descripción | | ------------------------------ | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Error de pago | [card_error](https://docs.stripe.com/error-handling.md#payment-errors) | Se ha producido un error durante un pago debido a alguno de estos motivos: - [Pago bloqueado por presunto fraude](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined). - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors). | | Errores de solicitud no válida | [invalid_request_error](https://docs.stripe.com/error-handling.md#invalid-request-errors) | 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 | [api_connection_error](https://docs.stripe.com/error-handling.md#connection-errors) | Ha habido un problema de red entre tu servidor y Stripe. | | Error de API | [api_error](https://docs.stripe.com/error-handling.md#api-errors) | Se produjo un error del lado de Stripe. (Esto no suele ocurrir). | | Error de autenticación | [authentication_error](https://docs.stripe.com/error-handling.md#authentication-errors) | Stripe no puede autenticarte con la información proporcionada. | | Error de idempotencia | [idempotency_error](https://docs.stripe.com/error-handling.md#idempotency-errors) | Has usado una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) para una acción inesperada, como repetir una solicitud con parámetros distintos. | | Error de permiso | [permission_error](https://docs.stripe.com/error-handling.md#permission-errors) | La clave de API usada para esta solicitud no tiene los permisos necesarios. | | Error de límite de velocidad | [rate_limit_error](https://docs.stripe.com/error-handling.md#rate-limit-errors) | Hiciste demasiadas llamadas API en muy poco tiempo. | | Error de verificación de firma | [signature_verification_error](https://docs.stripe.com/error-handling.md#signature-verification-errors) | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) *de webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no has podido verificar que un evento de webhook sea auténtico. | ## Errores de pago 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 [card_error](https://docs.stripe.com/error-handling.md#card-error). 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](https://docs.stripe.com/error-handling.md#payment-blocked) - [Pago rechazado por el emisor](https://docs.stripe.com/error-handling.md#payment-declined) - [Otros errores de pago](https://docs.stripe.com/error-handling.md#other-payment-errors) Para distinguir estas categorías u obtener más información sobre cómo responder, consulta el [código de error](https://docs.stripe.com/error-codes.md), el [código de rechazo](https://docs.stripe.com/declines/codes.md) y el [resultado del cargo](https://docs.stripe.com/api/charges/object.md#charge_object-outcome). (Para encontrar el resultado del cargo de un objeto de error, primero debes obtener el [PaymentIntent en cuestión](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge); if ($charge->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('Other card error.'); } } } ``` Usuarios en la versión de API [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) o anterior: (Para encontrar el resultado del cargo de un objeto de error, primero debes obtener el [PaymentIntent en cuestión](https://docs.stripe.com/api/errors.md#errors-payment_intent) y el [último Charge que creó](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-charges-data). Consulta el siguiente ejemplo para ver una demostración). #### PHP ```php >'); function example_function($args) { try { $stripe->paymentIntents->create($args); } catch(\Stripe\Exception\CardException $e) { if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') { error_log('Blocked for suspected fraud.'); } elseif ($e->getError()->code == 'expired_card') { error_log('Card expired.'); } elseif ($e->getError()->code == 'card_declined') { error_log('Declined by the issuer.'); } else { error_log('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](https://docs.stripe.com/testing.md#fraud-prevention) - [Simulación de pagos rechazados y otros errores de tarjeta](https://docs.stripe.com/testing.md#declined-payments) El código de prueba que figura a continuación muestra algunas posibilidades. #### Error al ejecutar - Bloqueado por presunto fraude #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_radarBlock', // Esta es una tarjeta de prueba que siempre se bloquea por supuesto fraude cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment blocked for suspected fraud. ``` #### Error al ejecutar - Rechazado por el emisor #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_visa_chargeDeclined', // Esta es una tarjeta de prueba que siempre rechaza el emisor cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Payment declined by the issuer ``` #### Error al ejecutar - Tarjeta caducada #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedExpiredCard', // Esta es una tarjeta de prueba que siempre falla como caducada cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Card expired. ``` #### Error al ejecutar - Otro error de tarjeta #### PHP ```php example_function([ 'currency' => 'usd', 'amount' => 2000, 'confirm' => True, 'payment_method' => 'pm_card_chargeDeclinedProcessingError', // Esta es una tarjeta de prueba que siempre falla debido a un error de procesamiento cuando la usas en un entorno de prueba. Usa esta y otras tarjetas de prueba para ver cómo funciona la gestión de errores en tu integración. En el código de producción, en este paso usarías un método de pago real. ]); ``` ``` Other payment error. ``` ### Pago bloqueado por presunto fraude | | | | | **Tipo** | `card_error` | | **Códigos** | ```dotnet var chargeService = new ChargeService(); var options = new ChargeGetOptions(); var charge = chargeService.Get(e.StripeError.PaymentIntent.LatestChargeId, options); charge.Outcome.Type == "blocked" ``` Users on API version [2022-08-01](https://docs.stripe.com/upgrades.md#2022-08-01) or older: | **Códigos** | `e.StripeError.PaymentIntent.Charges.Data[0].Outcome.Type == "blocked"` | | **Problema** | | El sistema de prevención de fraude de Stripe, *Radar* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), 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 la integración de Radar](https://docs.stripe.com/radar/optimize-fraud-signals.md) para recopilar información más detallada. - Usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) para elementos de formularios prediseñados y optimizados. Los clientes de *Radar for Fraud Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) 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](https://docs.stripe.com/radar/risk-settings.md). (Radar for Fraud Teams) - Para cambiar los criterios de bloqueo de un pago, usa [reglas personalizadas](https://docs.stripe.com/radar/rules.md). (Radar for Fraud Teams) Puedes probar la configuración de tu integración con [tarjetas de prueba que simulan fraude](https://docs.stripe.com/radar/testing.md). Si tienes reglas de Radar personalizadas, sigue los consejos de prueba de la [documentación de Radar](https://docs.stripe.com/radar/testing.md). | ### Pago rechazado por el emisor | | | | | **Tipo** | `card_error` | | **Códigos** | `e.StripeError.Code == "card_declined"` | | **Problema** | El 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](https://docs.stripe.com/declines/codes.md) para obtener respuestas apropiadas para cada código. También puedes: - [Sigue las recomendaciones para reducir los pagos rechazados del emisor](https://docs.stripe.com/declines/card.md#reducing-bank-declines). - Usa [Payment Links](https://docs.stripe.com/payment-links.md), [Checkout](https://docs.stripe.com/payments/checkout.md) o [Stripe Elements](https://docs.stripe.com/payments/elements.md) 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](https://docs.stripe.com/radar/testing.md). | ### Otros errores de pago | | | | | **Tipo** | `card_error` | | **Problema** | Se produjo otro error de pago. | | **Soluciones** | Este 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](https://docs.stripe.com/error-codes.md) para obtener respuestas apropiadas para cada código. | ## Errores de solicitudes no válidas | | | | | **Tipo** | `invalid_request_error` | | **Problema** | Has hecho una llamada a la 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. - Consulta la [documentación de códigos de error](https://docs.stripe.com/error-codes.md) para obtener más información sobre el problema. - 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** | `api_connection_error` | | **Problema** | Ha habido un problema de red entre tu servidor y Stripe. | | **Soluciones** | Trata el resultado de la llamada a la API como indeterminado. Es decir, no asumas que se ha llevado a cabo ni que ha fallado. 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. Para recuperarte de errores de conexión, puedes hacer lo siguiente: - Al crear o actualizar un objeto, usa una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md). Después, si se produce un error de conexión, puedes repetir la solicitud de forma segura sin riesgo de crear un segundo objeto ni de realizar la actualización dos veces. Repite la solicitud con la misma clave de idempotencia hasta que obtengas un resultado satisfactorio o de error. Para obtener consejos avanzados sobre esta estrategia, consulta [Tratamiento de errores avanzados](https://docs.stripe.com/error-low-level.md#idempotency). - Activa los [reintentos automáticos](https://github.com/stripe/stripe-java?tab=readme-ov-file#configuring-automatic-retries). 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** | `api_error` | | **Problema** | Se 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* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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](https://docs.stripe.com/error-low-level.md#server-errors). | ## Errores de autenticación | | | | | **Tipo** | `authentication_error` | | **Problema** | Stripe no puede autenticarte con la información proporcionada. | | **Soluciones** | - Utiliza la [clave de API](https://docs.stripe.com/keys.md) correcta. - Asegúrate de no estar usando una clave que hayas [«rotado» o anulado](https://docs.stripe.com/keys.md#rolling-keys). | ## Errores de idempotencia | | | | | **Tipo** | `idempotency_error` | | **Problema** | Has usado una [clave de idempotencia](https://docs.stripe.com/api/idempotent_requests.md) 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. | ## Errores de permisos | | | | | **Tipo** | `permission_error` | | **Problema** | La clave de API usada para esta solicitud no tiene los permisos necesarios. | | **Soluciones** | - Asegúrate de no estar usando una [clave de API restringida](https://docs.stripe.com/keys-best-practices.md#limit-access) para un servicio al que no tienes acceso. - No realices acciones en el Dashboard si has iniciado sesión con una [función de usuario](https://docs.stripe.com/get-started/account/teams/roles.md) que no tenga permiso. | ## Errores de límite de velocidad | | | | | **Tipo** | `rate_limit_error` | | **Problema** | Has 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](https://docs.stripe.com/rate-limits.md) 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](https://support.stripe.com/) por adelantado. | ## Errores de verificación de firma | | | | | **Tipo** | `signature_verification_error` | | **Problema** | Estás usando la [verificación de firma](https://docs.stripe.com/webhooks.md#verify-events) *de webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) y no has podido 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 cuando no deberías, por ejemplo, con webhooks que sabes que se originan en Stripe, consulta la documentación sobre [verificación de firma de webhook](https://docs.stripe.com/webhooks.md#verify-events) para obtener más consejos. En concreto, asegúrate de usar el secreto del punto de conexión correcto. Es diferente de la clave de API. |