# Límites de frecuencia

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

Stripe utiliza el límite de frecuencia para maximizar la estabilidad de la API y evitar abusos, por lo que debes tratar los límites como máximos y evitar cargas innecesarias.

Si excedes los límites, obtienes respuestas de estado HTTP `429 Demasiadas solicitudes`. Para obtener consejos sobre cómo manejar los errores `429`, consulta [Manejo adecuado de los límites](https://docs.stripe.com/rate-limits.md#handling-limiting-gracefully).

## Límites de frecuencia

En general, los límites de frecuencia se miden en solicitudes a la API por segundo, por cuenta de Stripe. El límite de frecuencia global se aplica al consumo total de la API por cuenta, mientras que algunos puntos de conexión tienen límites adicionales propios.

| Recurso | Límites |
| --- | --- |
| **Límite de frecuencia global de la API** | - *Modo activo* (Use this mode when you’re ready to launch your app. Card networks or payment providers process payments): 100 solicitudes por segundo
- *Entorno de prueba* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes): 25 solicitudes por segundo |
| Puntos de conexión de la API individuales (a menos que se indique lo contrario) | 25 solicitudes por segundo |
| [API Payment Intents](https://docs.stripe.com/api/payment_intents.md) | 1000 solicitudes de actualización por objeto PaymentIntent, por hora |
| [API Subscriptions](https://docs.stripe.com/api/subscriptions.md) | - 10 nuevas facturas por suscripción, por minuto
- 20 nuevas facturas por suscripción, por día
- 200 actualizaciones de por suscripción, por hora |
| [API Files](https://docs.stripe.com/api/files.md) | - 20 solicitudes de lectura por segundo
- 20 solicitudes de escritura por segundo |
| [API Payouts](https://docs.stripe.com/api/payouts.md) | - 15 solicitudes de [creación](https://docs.stripe.com/api/payouts/create.md) por segundo
- 30 [solicitudes simultáneas](https://docs.stripe.com/rate-limits.md#concurrency-limits) por empresa |
| Cuentas *Connect* (Connect is Stripe's solution for multi-party businesses, such as marketplace or software platforms, to route payments between sellers, customers, and other recipients), que incluyen:
- [Accounts v2](https://docs.stripe.com/api/v2/core/accounts.md)
- [Accounts v1](https://docs.stripe.com/api/accounts.md) | - *Modo activo* (Use this mode when you’re ready to launch your app. Card networks or payment providers process payments): crear 30 cuentas por segundo
- *Entorno de prueba* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes): crear 5 cuentas por segundo |
| [API Search](https://docs.stripe.com/search.md#rate-limits)1 | 20 solicitudes de lectura por segundo |
| [Emisión](https://docs.stripe.com/issuing.md) | Los límites de creación de tarjetas dependen del país y el sector de la cuenta emisora. |

Considera utilizar [Sigma](https://docs.stripe.com/data/sigma.md) o [Data Pipeline](https://docs.stripe.com/data/data-pipeline.md) como opciones más eficientes para tareas de análisis que requieren un gran volumen de datos.

## Límites de concurrencia

Los límites de concurrencia restringen la cantidad de solicitudes activas simultáneamente, independientemente de los límites de frecuencia. A diferencia de los límites de frecuencia, que en general se restablecen después de un segundo, el límite de concurrencia cuenta cuántas solicitudes están en curso en un momento dado. Alcanzar los límites de concurrencia es menos común que los errores de límite de frecuencia, y por lo general indican solicitudes de API de larga duración o que consumen muchos recursos, como las solicitudes de listas o las que incluyen [expansiones](https://docs.stripe.com/expand.md).

## Respuestas con límite de frecuencia

Las solicitudes que tienen límite de frecuencia devuelven un código de estado HTTP `429 Demasiadas solicitudes` e incluyen un encabezado `Stripe-Rate-Limited-Reason` que explica por qué se aplicó el límite a la solicitud. Los valores posibles para este encabezado son:

| Valor del encabezado | Significado |
| --- | --- |
| `global-rate` | Excediste el límite de frecuencia global. Puedes evitarlo con el envío de solicitudes a una frecuencia menor. |
| `endpoint-rate` | Excediste el límite de frecuencia para las solicitudes a este punto de conexión de la API en particular. Puedes evitarlo con el envío de solicitudes a este punto de conexión a una frecuencia menor. |
| `global-concurrency` | Excediste el límite de concurrencia global. Puedes evitarlo con el envío de menos solicitudes simultáneas. |
| `endpoint-concurrency` | Excediste el límite de concurrencia para las solicitudes a este punto de conexión de la API en particular. Puedes evitarlo con el envío de menos solicitudes simultáneas a este punto de conexión específico. |
| `resource-specific` | Excediste el límite de frecuencia relacionado con las solicitudes a cualquier punto de conexión dentro de este recurso, por ejemplo, los puntos de conexión de creación y actualización de suscripciones. Puedes evitarlo con el envío de solicitudes a los puntos de conexión de ese recurso a una frecuencia menor. |

Si una solicitud devuelve un código de estado `429` sin estos encabezados, no fue el resultado de un límite de frecuencia. Podría tratarse de un [tiempo de espera de bloqueo agotado](https://docs.stripe.com/rate-limits.md#object-lock-timeouts).

## 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](https://docs.stripe.com/rate-limits.md#handling-limiting-gracefully)).

- 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](https://support.stripe.com/).

- La emisión de muchas solicitudes de larga duración puede activar el límite de concurrencia. 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](https://docs.stripe.com/expand.md) 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 identificar las que sean inesperadamente lentas.

## 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](https://en.wikipedia.org/wiki/Thundering_herd_problem).

Un enfoque más sofisticado es controlar el tráfico hacia Stripe a nivel global y reducirlo si detectas un límite de frecuencia sustancial. Una técnica común para controlar el consumo de la API es implementar un algoritmo del lado del cliente para establecer un límite de frecuencia que asigne [tokens por bucket](https://en.wikipedia.org/wiki/Token_bucket). Las implementaciones o bibliotecas de bucket de tokens están disponibles para la mayoría de los lenguajes 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 API o un proceso de Stripe está accediendo a él. Si este error aparece en forma intermitente, vuelve a intentar la solicitud. Si el error aparece con frecuencia y estás haciendo varias solicitudes a la vez para un solo objeto, debes hacer tus 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](https://docs.stripe.com/api/request_ids.md).

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](https://docs.stripe.com/rate-limits.md#handling-limiting-gracefully)). 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](https://docs.stripe.com/sdks.md) de Stripe hará el reintento de los errores `429` causados por tiempos de espera de bloqueo:

#### Ruby

```ruby
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](https://docs.stripe.com/data.md)
- [Productos de elaboración de informes](https://docs.stripe.com/stripe-reports.md)
- [Productos de impuestos](https://docs.stripe.com/tax.md)

Para reducir el volumen de solicitudes de API, considera usar [Stripe Data Pipeline](https://docs.stripe.com/data/data-pipeline.md) a fin de obtener una exportación completa de los datos de la API y guardarla en tu base de datos o proveedor local.

> #### Filtra solicitudes para limitar las llamadas paginadas
> 
> Algunos puntos de conexión de listas devuelven [varias páginas](https://docs.stripe.com/api/pagination.md) de resultados y es posible que requieran varias solicitudes para devolver el conjunto completo de objetos de la API a fin de operar una lista. Cuando sea posible, aplica los filtros para limitar los resultados de tu lista.