Límites de frecuencia

La API de Stripe utiliza una serie de medidas de protección contra los aluviones de tráfico entrante para maximizar su estabilidad. Si envías muchas solicitudes en sucesión rápida, es posible que veas respuestas de error con el código de estado 429.

Limitadores de API

Tenemos varios limitadores en la API, incluyendo un limitador de frecuencia y uno de concurrencia.

Trata los límites como máximos y no generes una carga innecesaria. Para evitar abusos, podríamos reducir los límites.

Para obtener consejos sobre cómo manejar los errores 429, consulta Cómo manejar los límites correctamente. Si de repente ves que aumenta la cantidad de solicitudes limitadas, contacta con Soporte de Stripe.

Puedes solicitar un aumento del límite para habilitar una aplicación de alto tráfico poniéndote en contacto con Soporte de Stripe. Si necesitas un aumento importante, contáctanos con al menos 6 semanas de anticipación.

Limitador de frecuencia

El limitador de frecuencia básico restringe el número de solicitudes de API por segundo de la siguiente manera:

• Modo activo: 100 operaciones
• Entorno de prueba: 25 operaciones

Las llamadas a recursos individuales tienen límites más estrictos y también cuentan para los límites globales. Los puntos de conexión de API tienen un límite predeterminado de 25 solicitudes por segundo. Stripe puede aumentar los límites de frecuencia para cuentas específicas en función del consumo.

• API Files: 20 operaciones de lectura y 20 operaciones de escritura por segundo
• API de búsqueda: 20 operaciones de lectura por segundo

Las llamadas al punto de conexión de eventos del medidor en modo activo están sujetas a un límite de frecuencia por separado y no cuentan para los límites básicos. El límite es de 1000 llamadas por segundo por cuenta de Stripe. En un entorno de prueba, las llamadas al punto de conexión de eventos del medidor cuentan para el límite básico. En el caso de las plataformas de Connect, las llamadas en una cuenta conectada al punto de conexión de eventos del medidor también cuentan para el límite básico.

Solicitudes con límite de frecuencia

Las solicitudes con un límite de frecuencia devuelven el encabezado Stripe-Rate-Limited-Reason con valores que indican el límite de frecuencia que superó la solicitud. Estos son los valores posibles para este encabezado:

• global-concurrency: Tus solicitudes han superado el límite global de simultaneidad. Puedes evitarlo enviando menos solicitudes simultáneas.
• global-rate: Tus solicitudes han excedido el límite de frecuencia global. Puedes evitarlo enviando solicitudes a una velocidad menor.
• endpoint-concurrency: Tus solicitudes a este punto de conexión de API específico han superado el límite de simultaneidad. Puedes evitarlo enviando menos solicitudes simultáneas a este punto de conexión específico.
• endpoint-rate: Tus solicitudes a este punto de conexión de API específico han superado el límite de frecuencia. Puedes evitarlo enviando solicitudes a este punto de conexión a una velocidad menor.
• resource-specific: Alcanzaste un límite de frecuencia relacionado con un recurso de API específico. Consulta la documentación de ese recurso para obtener más información.

Si una solicitud arroja un código de estado 429 sin estos encabezados, no fue el resultado de un limitador de frecuencia (por ejemplo, puede ser un tiempo de espera de bloqueo).

Limitador de concurrencia

El limitador de concurrencia restringe el número de solicitudes activas concurrentes. Los problemas con este limitador son menos comunes que con el limitador de frecuencia, pero es probable que indiquen la existencia de solicitudes de larga duración y uso intensivo de recursos.

Las llamadas al punto de conexión de eventos del medidor están limitadas a una llamada concurrente por cliente por medidor.

Causas comunes y mitigaciones

La limitación de velocidad puede producirse en diferentes condiciones, pero es más común en los siguientes casos:

• Ejecutar un gran volumen de solicitudes muy próximas puede llevar a una limitación de la velocidad. A menudo, esto forma parte de operaciones analíticas o de migración. Cuando estés haciendo estas actividades, debes tratar de controlar la tasa de solicitudes de lado del cliente (consulta Cómo manejar los límites correctamente).
• La emisión de muchas solicitudes de larga duración puede activar la limitación. Las solicitudes utilizan diferentes cantidades de recursos del servidor de Stripe. Las solicitudes que demandan más recursos tienden a insumir más tiempo, y esto puede llevar al limitador de concurrencia a suprimir las nuevas solicitudes. Los requisitos de recursos varían mucho, pero las solicitudes de listas y las solicitudes que incluyen expansiones suelen usar más recursos e insumen más tiempo de ejecución. Sugerimos trazar el perfil de duración de las solicitudes de la API de Stripe y observar los tiempos de espera para tratar de detectar aquellas que sean inesperadamente lentas.
• Un aumento repentino en el volumen de cargos, como una venta con grandes descuentos podría generar una limitación de la frecuencia. Intentamos establecer nuestras tarifas lo suficientemente altas como para que el tráfico de pagos legítimo no exceda los límites, pero si sospechas que un próximo evento podría llevarte a superar los límites enumerados arriba, ponte en contacto con el soporte de Stripe.

Cómo manejar los límites correctamente

Una técnica básica para que las integraciones manejen correctamente los límites consiste en observar los códigos de error 429 y crear un mecanismo de reintentos. Este mecanismo debe seguir un calendario de retroceso exponencial para reducir el volumen de solicitudes cuando sea necesario. También recomendamos agregar algo de aleatoriedad al calendario para evitar el efecto de estampida.

Debido a que las solicitudes individuales se pueden optimizar solo hasta cierto punto, un enfoque más sofisticado consistiría en controlar el tráfico hacia Stripe a nivel global y moderarlo si detectaras una limitación de velocidad importante. Una técnica común para controlar la velocidad es implementar, por ejemplo, un algoritmo de limitación de velocidad “token bucket” de lado del cliente. Hay implementaciones ya preparadas y probadas para “token bucket” disponibles en casi cualquier lenguaje de programación.

Tiempos de espera de bloqueo de objetos

Las integraciones pueden encontrar errores con el estado HTTP 429, el código lock_timeout y este mensaje:

No se puede acceder a este objeto en este momento porque otra solicitud de la API u otro proceso de Stripe está accediendo a él. Si este error aparece de forma intermitente, vuelve a intentar la solicitud. Si este error aparece con frecuencia y estás haciendo varias solicitudes a la vez para un solo objeto, haz las solicitudes de manera secuencial o a menor velocidad.

La API de Stripe bloquea objetos en algunas operaciones para que las cargas de trabajo concurrentes no generen interferencias y resultados incoherentes. El error indicado arriba se produce por una solicitud que trata de adquirir un bloqueo que ya se utiliza en otro lugar y que se agota antes de poder adquirirlo.

Los tiempos de espera de bloqueo y los límites de frecuencia tienen causas diferentes, pero sus mitigaciones son similares. Al igual que para los errores por límite de frecuencia, recomendamos volver a intentar con un calendario de retroceso exponencial (consulta Cómo manejar los límites correctamente). Sin embargo, a diferencia de lo que sucede con los errores por límite de frecuencia, el mecanismo de reintento automático integrado a las SDK de Stripe hará el reintento de los errores 429 causados por tiempos de espera de bloqueo:

Stripe.max_network_retries = 2

La contención de bloqueo se debe al acceso concurrente a objetos relacionados. Las integraciones pueden reducirlo considerablemente asegurándose de que las mutaciones en el mismo objeto se pongan en una cola y se ejecuten en forma secuencial. Se pueden seguir haciendo operaciones concurrentes con la API, pero trata de cerciorarte de que las operaciones simultáneas se hagan solo sobre objetos únicos. También es posible ver una contención de bloqueo a causa de un conflicto con un proceso interno de Stripe en segundo plano. Es raro, pero debido a que está más allá del control del usuario, recomendamos que todas las integraciones sean capaces de hacer reintentos de solicitudes.

Prueba de carga

Es habitual que los usuarios se preparen para un evento de ventas importante mediante pruebas de carga de sus sistemas, con la API de Stripe ejecutándose en un entorno de prueba como parte de él. Por lo general, desaconsejamos esta práctica porque los límites de API son más bajos en un entorno de prueba. Entonces, es probable que la prueba de carga alcance límites que no alcanzaría en modo activo. Un entorno de prueba tampoco es un equivalente perfecto para las llamadas API en modo activo, y eso puede ser un tanto engañoso. Por ejemplo, la creación de un cargo en modo activo envía una solicitud a una pasarela de pagos, pero esa solicitud en el entorno de prueba es una simulación y, por lo tanto, arroja perfiles de latencia muy diferentes.

Recomendamos, en cambio, crear integraciones que cuenten con un sistema configurable que permita simular las solicitudes a la API de Stripe y que puedas activar para pruebas de carga. Para obtener resultados realistas, deben simular la latencia aguardando un tiempo de suspensión determinado mediante el muestreo de las duraciones de llamadas reales a la API de Stripe en modo activo, desde la perspectiva de la integración.

Asignaciones de solicitud de lectura de la API

Stripe proporciona acceso a sus solicitudes de lectura de la API (GET) para facilitar búsquedas razonable relacionadas con las integraciones de pagos. A fin de maximizar la calidad del servicio para todos los usuarios, Stripe proporciona las siguientes asignaciones para las solicitudes de lectura basadas en el recuento de transacciones:

• Las solicitudes de lectura de la API no deben exceder una proporción promedio de 500 solicitudes por transacción para una cuenta. Por ejemplo, si una cuenta procesa 100 transacciones en un período de 30 días, no deben exceder las 50,000 solicitudes de lectura de la API durante ese mismo período.
• Cuando se usa Connect, una plataforma y sus cuentas conectadas tienen distintas autorizaciones de lectura de la API:
  • Cada cuenta conectada tiene su propia asignación para las solicitudes que inician (500 solicitudes por transacción).
  • Las plataformas Connect utilizan una asignación independiente para realizar solicitudes de lectura en nombre de sus cuentas conectadas con su clave de API secreta o tokens de acceso OAuth. Esta asignación también es de 500 solicitudes por transacción en función del recuento acumulado de transacciones en sus cuentas conectadas.
• Las proporciones se miden cada 30 días.
• Cada cuenta, independientemente del recuento de transacciones, tiene una asignación mínima de 10,000 solicitudes de lectura por mes.
• Las solicitudes de escritura de la API no tienen límite de asignación.

Las llamadas a los siguientes puntos de conexión de la API no se incluyen en los límites de asignación anteriores:

• Productos de datos
• Productos de elaboración de informes
• Productos de impuestos

Para reducir el volumen de solicitudes de API, considera usar Stripe Data Pipeline a fin de obtener una exportación completa de los datos de la API y guardarla en tu base de datos o proveedor local.