# Límites de velocidad

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

Stripe usa el límite de frecuencia para maximizar la estabilidad de la API y evitar el abuso, así que trata los límites como máximos y evita las cargas innecesarias.

Si superas los límites, recibirás una respuesta de estatus HTTP `429 Too Many Requests`. Si necesitas consejos sobre cómo tratar los errores `429`, consulta [Cómo gestionar con éxito las limitaciones](https://docs.stripe.com/rate-limits.md#handling-limiting-gracefully).

## Límites de frecuencia

Por lo general, los límites de frecuencia se miden en peticiones a la API por segundo, por cuenta de Stripe. El límite de frecuencia global se aplica al consumo de la API total por cuenta, pero algunos puntos de conexión cuentan con límites adicionales propios.

Stripe considera cada operación de la API designada como un punto de conexión independiente (por ejemplo, `POST /v1/payment_intents` y `GET /v1/payment_intents/{id}` son puntos de conexión independientes). Las solicitudes a `GET /v1/payment_intents/{id}` para diferentes ID de PaymentIntent cuentan para el mismo límite del punto de conexión.

| Recurso | Límites |
| --- | --- |
| **Límite de frecuencia de la API global** | - *Modo activo* (Use this mode when you’re ready to launch your app. Card networks or payment providers process payments): 100 peticiones 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 peticiones por segundo |
| Puntos de conexión a la API individuales (salvo que se indique lo contrario) | 25 peticiones por segundo |
| [API Payment Intents](https://docs.stripe.com/api/payment_intents.md) | 1000 peticiones de actualización por objeto PaymentIntent por hora |
| [Subscripciones API](https://docs.stripe.com/api/subscriptions.md) | - 10 facturas nuevas por suscripción, por minuto
- 20 facturas nuevas por suscripción al día
- 200 actualizaciones de cantidad por suscripción, por hora |
| [Archivos API](https://docs.stripe.com/api/files.md) | - 20 peticiones de lectura por segundo
- 20 peticiones de escritura por segundo |
| [Transferencias API](https://docs.stripe.com/api/payouts.md) | - 15 peticiones de [creación](https://docs.stripe.com/api/payouts/create.md) por segundo
- 30 [peticiones simultáneas](https://docs.stripe.com/rate-limits.md#concurrency-limits) por empresa |
| Las cuentas de *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), lo que incluye:
- [Cuentas v2](https://docs.stripe.com/api/v2/core/accounts.md)
- [Cuentas 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): crea 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): crea 5 cuentas por segundo |
| [Buscar API](https://docs.stripe.com/search.md#rate-limits)1 | 20 peticiones de lectura por segundo |
| [Issuing](https://docs.stripe.com/issuing.md) | Los límites de creación de tarjetas dependen del país y el sector de la cuenta de emisión. |

Considera usar [Sigma](https://docs.stripe.com/data/sigma.md) o [Data Pipeline](https://docs.stripe.com/data/data-pipeline.md) si quieres opciones más eficientes para tareas analíticas que requieran muchos datos.

## Límites de simultaneidad

Los límites de simultaneidad restringen el número de peticiones activas simultáneamente y son distintos del límite de frecuencia. A diferencia de este, que suele restablecerse después de un segundo, el límite de simultaneidad contabiliza las peticiones en curso en un momento determinado. No es tan frecuente alcanzar los límites de simultaneidad como los errores por límite de frecuencia, pero normalmente son indicio de peticiones a la API persistentes o que consumen muchos recursos, como las de lista o aquellas que incluyen [expansiones](https://docs.stripe.com/expand.md).

## Respuestas por un límite de frecuencia superado

Las peticiones con un límite de frecuencia superado devuelven un código de estatus HTTP `429 Too Many Requests` e incluyen un encabezado `Stripe-Rate-Limited-Reason` que explica el motivo de la limitación. Los posibles valores del encabezado son:

| Valor de encabezado | Significado |
| --- | --- |
| `global-rate` | Has superado el límite de frecuencia global. Puedes evitar que esto suceda enviando solicitudes con menor frecuencia. |
| `endpoint-rate` | Has superado el límite de frecuencia para las solicitudes a este punto de conexión a la API específico. Puedes evitar que esto suceda enviando solicitudes a este punto de conexión con menor frecuencia. |
| `global-concurrency` | Has superado el límite de simultaneidad global. Puedes evitar que esto suceda enviando menos solicitudes simultáneas. |
| `endpoint-concurrency` | Has superado el límite de simultaneidad para las solicitudes a este punto de conexión a la API específico. Puedes evitar que esto suceda enviando menos solicitudes simultáneas a este punto de conexión específico. |
| `resource-specific` | Has superado 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 actualización y creación de suscripciones. Puedes evitar que esto suceda enviando solicitudes a los puntos de conexión de todo ese recurso con menor frecuencia. |

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

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

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

- Aceptar demasiadas peticiones persistentes puede desencadenar el límite de simultaneidad. Las solicitudes varían en la cantidad de recursos que consumen del servidor de Stripe. Aquellas que consumen muchos recursos pueden prolongarse más, con el riesgo de que el limitador de simultaneidad anule nuevas peticiones. Pese a la gran variación en los requisitos, las peticiones de listas o que incluyen [expansiones](https://docs.stripe.com/expand.md) suelen consumir más recursos y prolongarse. Recomendamos crear perfiles de la duración de las peticiones a la API de Stripe y vigilar los tiempos de espera de las posibles peticiones inesperadamente lentas.

## Gestionar límites

Presta atención a los códigos de estatus `429` e implementa un mecanismo de reintento para gestionar la limitación de velocidad. Sigue un programa de retroceso exponencial para reducir el volumen de peticiones cuando sea necesario, y añade aleatoriedad al programa de retroceso para evitar un [efecto avalancha](https://en.wikipedia.org/wiki/Thundering_herd_problem).

Una alternativa más sofisticada es controlar el tráfico a Stripe a nivel general y reducirlo si detectas un límite de frecuencia importante. Una técnica común de control del consumo de la API es implementar en el lado del cliente un [algoritmo de token bucket](https://en.wikipedia.org/wiki/Token_bucket). Las implementaciones del paquete de tokens o las bibliotecas están disponibles en la mayoría de los lenguajes 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 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 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. Stripe no procesa estas peticiones 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 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](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 velocidad, el mecanismo de reintento automático integrado en los [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 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 la 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 la API leídas de tu cuenta no deben superar una media de 500 por transacción. Por ejemplo, si procesas 100 transacciones en 30 días, no debes superar las 50.000 peticiones de lectura de la API durante ese 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.

- Los ratios se calculan en un período móvil de 30 días (los 30 días más recientes).

- 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:

- [Productos de datos](https://docs.stripe.com/data.md)
- [Productos para la elaboración de informes](https://docs.stripe.com/stripe-reports.md)
- [Productos para impuestos](https://docs.stripe.com/tax.md)

Para reducir el volumen de tus peticiones a la API, considera usar [Data Pipeline](https://docs.stripe.com/data/data-pipeline.md) para una exportación completa de los datos de la API a la base de datos o el proveedor que uses a nivel local.

> #### Filtra las peticiones para limitar las llamadas paginadas
> 
> Algunos puntos de conexión de la lista devuelven [varias páginas](https://docs.stripe.com/api/pagination.md) 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.

## Request a limit increase

Request a limit increase for high-traffic applications through [Stripe Support](https://support.stripe.com/contact). If you request a large increase, contact Stripe Support at least 6 weeks in advance.