Límites de velocidad

Obtén más información sobre los límites de velocidad de API y cómo trabajar con ellos.

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

Limitadores de la API

Tenemos varios limitadores en la API, incluidos un limitador de velocidad y un limitador de concurrencia.

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

Para obtener consejos sobre la gestión de los errores 429, consulta Cómo gestionar los límites correctamente. Si de repente ves que aumenta la cantidad de peticiones con limitación de velocidad, ponte en contacto con el soporte de Stripe.

Puedes solicitar un aumento del límite para habilitar una aplicación de tráfico elevado poniéndote en contacto con el soporte de Stripe. Si solicitas un aumento importante, ponte en contacto con nosotros con al menos 6 semanas de antelación.

Limitador de velocidad

El limitador de velocidad básico restringe la cantidad de peticiones 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 la 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 Search: 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 velocidad separado y no se incluyen en los límites básicos. El límite es de 1000 llamadas por segundo por cuenta de Stripe. En un entorno aislado, las llamadas al punto de conexión de eventos del medidor cuentan para el límite básico. En el caso de las plataformas Connect, las llamadas de una cuenta conectada al punto de conexión de eventos del medidor también se tienen en cuenta para el límite básico.

Solicitudes con limitación de frecuencia

Las solicitudes con límite de frecuencia devuelven el encabezado Stripe-Rate-Limited-Reason con valores que indican qué límite de frecuencia ha superado la solicitud. Los valores posibles para este encabezado son:

global-concurrency: Las solicitudes han superado el límite global de concurrencia. Puedes evitarlo enviando menos solicitudes concurrentes.
global-rate: Tus solicitudes han superado el límite de frecuencia global. Puedes evitarlo enviando solicitudes a una frecuencia más baja.
endpoint-concurrency: Las solicitudes a este punto de conexión de API específico han superado el límite de concurrencia. Puedes evitarlo enviando menos solicitudes concurrentes este punto de conexión específico.
endpoint-rate: Tus solicitudes a este punto de conexión de API específico han excedido el límite de frecuencia. Puedes evitarlo enviando solicitudes a este punto de conexión a una frecuencia más baja.
resource-specific: Has alcanzado 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 devuelve un código de estado 429 sin estos encabezados, no se ha debido a un limitador de frecuencia (por ejemplo, puede ser un tiempo de espera de bloqueo).

Limitador de concurrencia

El limitador de concurrencia restringe la cantidad de peticiones activas concurrentes. Los problemas con este limitador son menos comunes que con el limitador de velocidad, pero es probable que indiquen la existencia de peticiones de larga duración y que requieren muchos recursos.

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

Mitigaciones y causas habituales

La limitación de velocidad puede producirse en diferentes condiciones, pero suele darse en las siguientes situaciones:

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 intentar controlar la tasa de solicitudes del lado del cliente (consulta Cómo gestionar 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 requieren más recursos tienden a llevar más tiempo, y conlleva el riesgo de que el limitador de concurrencia retire 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 y 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 oferta relámpago, podría resultar en una limitación de la velocidad. Tratamos de establecer nuestras velocidades lo suficientemente altas como para que el tráfico de pagos legítimos nunca supere los límites, pero si sospechas que un próximo evento podría llevarte a exceder los límites mencionados anteriormente, ponte en contacto con el soporte de Stripe.

Cómo gestionar los límites correctamente

Una técnica básica para que las integraciones gestionen 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 añadir algo de aleatoriedad al calendario de retroceso para evitar el efecto “Thundering Herd”.

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 reducirlo si detectaras una limitación de velocidad importante. Una técnica habitual 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

Es posible que en las integraciones haya errores con el estado HTTP 429, el código lock_timeout y el siguiente mensaje:

No se puede acceder a este objeto en este momento porque actualmente está accediendo otra solicitud de API o proceso de Stripe. Si este error aparece de forma intermitente, vuelve a intentar la solicitud. Si el error aparece con frecuencia y haces varias solicitudes concurrentes 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 interfieran y generen resultados incoherentes. El error indicado arriba se produce por una solicitud que intenta adquirir un bloqueo que ya se utiliza en otro lugar y que se agota antes de poder adquirirlo a tiempo.

Los tiempos de espera de bloqueo y los límites de velocidad tienen causas diferentes, pero sus mitigaciones son similares. Al igual que para los errores por límite de velocidad, recomendamos volver a probar 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 velocidad, el mecanismo de reintento automático integrado en los SDK de Stripe hará el reintento de los errores 429 causados por tiempos de espera de bloqueo:

La contención de bloqueo se debe al acceso concurrente a objetos relacionados. Las integraciones pueden reducirlo considerablemente al asegurarse de que las mutaciones en el mismo objeto se pongan en 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 puedan hacer reintentos de solicitudes.

Prueba de carga

Es habitual que los usuarios se preparen para un evento de ventas importante realizando pruebas de carga de sus sistemas y que ejecuten la API de Stripe en un entorno aislado como parte de ello. Por lo general, desaconsejamos esta práctica porque los límites de la API son más bajos en un entorno de prueba, por lo que es probable que la prueba de carga alcance límites que no alcanzaría en producción. Un entorno de prueba tampoco es un sustituto perfecto para las llamadas a la API en modo activo, pues puede ser algo engañoso. Por ejemplo, al crear un cargo en modo activo, se envía una solicitud a una pasarela de pagos y esa solicitud se simula en un entorno de prueba, lo que da lugar a perfiles de latencia significativamente diferentes.

Como alternativa, recomendamos crear integraciones de manera que tengan un sistema configurable para simular peticiones a la API de Stripe, que puedas habilitar para pruebas de carga. Para obtener resultados realistas, se debe simular la latencia dejando un tiempo de suspensión que determinas mediante el muestreo de las duraciones de las llamadas reales a la API de Stripe en modo activo, visto desde la perspectiva de la integración.

Asignaciones de peticiones de lectura de API

Stripe ofrece acceso a sus peticiones de API de lectura (GET) para facilitar una actividad de búsqueda razonable en relación con las integraciones de pagos. Para maximizar la calidad del servicio para todos los usuarios, Stripe proporciona las siguientes asignaciones para peticiones de lectura basadas en la cantidad de transacciones:

Las peticiones de API de lectura no deben exceder una relación promedio de 500 peticiones 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 peticiones de API de lectura durante ese mismo período.
Al usar Connect, una plataforma y sus cuentas conectadas tienen autorizaciones de API de lectura diferentes:
- Cada cuenta conectada tiene su propia asignación para las peticiones que inician (500 peticiones por transacción).
- Las plataformas Connect utilizan una asignación separada para realizar peticiones 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 peticiones por transacción en función de la cantidad de transacciones acumuladas en sus cuentas conectadas.
Las relaciones se miden con una periodicidad de 30 días consecutivos.
Cada cuenta, independientemente del número de transacciones, tiene una asignación mínima de 10.000 peticiones de lectura por mes.
Las peticiones de API de escritura no tienen límites de asignación.

Las llamadas a los siguientes puntos de conexión de la API están excluidas de los límites de asignación anteriores:

Para reducir el volumen de peticiones de API, considera la opción de usar Stripe Data Pipeline para exportar completamente los datos de la API a tu base de datos local o proveedor.

Filtra las peticiones para limitar las llamadas paginadas

Algunos puntos de conexión de la lista devuelven varias páginas de resultados y podrían requerir múltiples peticiones para devolver el conjunto completo de objetos de API para una operación de la lista. Aplica filtros cuando sea posible para limitar los resultados de la lista.