Límites de frecuencia

Utilizamos protecciones contra ráfagas de tráfico entrante para maximizar la estabilidad de la API. Si envías muchas solicitudes en sucesión rápida, es posible que recibas respuestas de error 429.

Limitadores de API

Aplicamos varios limitadores de API, incluidos limitadores de frecuencia y concurrencia. Trata los límites como máximos y evita cargas innecesarias. Para evitar abusos, podríamos reducir tus límites. Para obtener consejos sobre cómo gestionar los errores 429, consulta Cómo gestionar los límites correctamente. Si ves un aumento en las solicitudes de límite de frecuencia, ponte en contacto con el soporte de Stripe.

Solicita un aumento del límite para las aplicaciones de alto tráfico mediante el soporte de Stripe. Si solicitas un aumento grande, ponte en contacto con el soporte de Stripe al menos con 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 Payment Intents: 1000 operaciones de actualización por PaymentIntent, por hora.
• API Files: 20 operaciones de lectura y 20 operaciones de escritura por segundo.
• API Search: 20 operaciones de lectura por segundo.
• Suscripciones API:
  • 10 nuevas facturas por suscripción, por minuto.
  • 20 nuevas facturas por suscripción, por día.
  • 200 actualizaciones por suscripción, por hora.
• API para transferencias: 15 solicitudes por segundo y 30 solicitudes concurrentes por comerciante.
• Connect: las plataformas pueden crear hasta 5 cuentas por segundo en entornos de prueba y 30 cuentas por segundo en modo activo.
• Issuing: la creación de tarjetas tiene límites de frecuencia que dependen del país y el sector de la empresa.

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 de 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 pueden 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.

Administración de límites

Presta atención a los códigos de estado 429 e implementa un mecanismo de reintento para gestionar el límite de frecuencia. Sigue un calendario de retroceso exponencial a fin de reducir el volumen de solicitudes cuando sea necesario y agrega aleatoriedad al calendario de retroceso para evitar el efecto manada.

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 simultáneas no interfieran y produzcan un resultado inconsistente. El error anterior se debe a que una solicitud intenta adquirir un bloqueo que ya está en uso en otro lugar y se agota el tiempo de espera al no poder adquirirlo a tiempo. Stripe no procesa estas solicitudes fallidas, lo que significa que no se les asigna un ID de solicitud.

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 de 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 API leídas de tu cuenta no deben superar un promedio de 500 por transacción. Por ejemplo, si procesas 100 transacciones en 30 días, no debes superar las 50,000 solicitudes de API leídas durante ese 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 relaciones se calculan en un período de 30 días consecutivos (los últimos 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.