# Limitações de fluxo

Conheça as limitações de fluxo da API e saiba como trabalhar com elas.

A Stripe usa a limitação de fluxo para maximizar a estabilidade da API e evitar abusos. Portanto, trate os limites como máximos e evite sobrecargas desnecessárias.

Se você exceder os limites, receberá respostas de status HTTP `429 Too Many Requests`. Para obter dicas sobre como lidar com erros `429`, consulte [Como lidar com limitações sem problemas](https://docs.stripe.com/rate-limits.md#handling-limiting-gracefully).

## Limitação de fluxo

Em geral, as limitações de fluxo são medidas em solicitações de API por segundo, por conta Stripe. A limitação do fluxo global se aplica ao uso total da API por conta, mas alguns endpoints têm limites adicionais próprios.

| Recurso | Limites |
| --- | --- |
| **Limitação de fluxo global da API** | - *Modo de produção* (Use this mode when you’re ready to launch your app. Card networks or payment providers process payments): 100 solicitações por segundo
- *Área restrita* (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 solicitações por segundo |
| Endpoints individuais de API (exceto quando indicado de outra forma) | 25 solicitações por segundo |
| [API Payment Intents](https://docs.stripe.com/api/payment_intents.md) | 1.000 solicitações de atualização por objeto PaymentIntent, por hora |
| [API Subscriptions](https://docs.stripe.com/api/subscriptions.md) | - 10 novas faturas por assinatura, por minuto
- 20 novas faturas por assinatura, por dia
- 200 atualizações de quantidade por assinatura, por hora |
| [API Files](https://docs.stripe.com/api/files.md) | - 20 solicitações de leitura por segundo
- 20 solicitações de gravação por segundo |
| [API Payouts](https://docs.stripe.com/api/payouts.md) | - 15 solicitações de [criação](https://docs.stripe.com/api/payouts/create.md) por segundo
- 30 [solicitações simultâneas](https://docs.stripe.com/rate-limits.md#concurrency-limits) por empresa |
| Contas *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), incluindo ambas:
- [Accounts v2](https://docs.stripe.com/api/v2/core/accounts.md)
- [Accounts v1](https://docs.stripe.com/api/accounts.md) | - *Modo de produção* (Use this mode when you’re ready to launch your app. Card networks or payment providers process payments): Crie 30 contas por segundo
- *Área restrita* (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): Crie 5 contas por segundo |
| [API Search](https://docs.stripe.com/search.md#rate-limits)1 | 20 solicitações de leitura por segundo |
| [Issuing](https://docs.stripe.com/issuing.md) | Os limites de criação de cartões dependem do país e do setor da conta emissora. |

Considere o [Sigma](https://docs.stripe.com/data/sigma.md) ou o [Data Pipeline](https://docs.stripe.com/data/data-pipeline.md) para obter opções mais eficientes em tarefas de análise com uso intensivo de dados.

## Limites de simultaneidade

Os limites de simultaneidade restringem o número de solicitações ativas ao mesmo tempo, separados das limitações de fluxo. Diferentemente da limitação de fluxo, que, em geral, é redefinida após um segundo, o limite de simultaneidade conta quantas solicitações estão em andamento em um determinado momento. Atingir os limites de simultaneidade é menos comum do que erros de limitação de fluxo e, geralmente, indica solicitações de API de longa duração ou com uso intensivo de recursos, como solicitações de lista ou que incluem [expansões](https://docs.stripe.com/expand.md).

## Respostas com limitação de fluxo

As solicitações com limitação de fluxo retornam um código de status HTTP `429 Too Many Requests` e incluem um cabeçalho `Stripe-Rate-Limited-Reason` que explica o motivo pelo qual a solicitação foi limitada. Os possíveis valores para este cabeçalho são:

| Valor do cabeçalho | Significado |
| --- | --- |
| `global-rate` | Suas solicitações excederam o limite de limitação de fluxo global. Você pode evitar isso enviando solicitações em uma taxa menor. |
| `endpoint-rate` | Suas solicitações a este endpoint de API específico excederam o limite de limitação de fluxo. Você pode evitar isso enviando solicitações a esse endpoint em uma taxa menor. |
| `global-concurrency` | Suas solicitações excederam o limite de simultaneidade global. Você pode evitar isso enviando menos solicitações simultâneas. |
| `endpoint-concurrency` | Suas solicitações a este endpoint de API específico excederam o limite de simultaneidade. Você pode evitar isso enviando menos solicitações simultâneas a esse endpoint específico. |
| `resource-specific` | Você atingiu um limite de limitação de fluxo relacionada a um recurso de API específico. Consulte a documentação desse recurso para obter mais informações. |

Se uma solicitação retornar um código de status `429` sem esses cabeçalhos, isso não foi resultado de um limite de limitação de fluxo. Pode ser um [tempo limite de bloqueio](https://docs.stripe.com/rate-limits.md#object-lock-timeouts).

## Causas e mitigações comuns

A limitação de fluxo pode ocorrer em diversas condições, mas é mais comum nestes cenários:

- A execução de **um grande volume de solicitações em pouco tempo** pode acionar a limitação de fluxo. Normalmente, isso ocorre em operações analíticas ou de migração. Nessas atividades, você deve tentar controlar a taxa de solicitações no lado do cliente (consulte [Processar limites corretamente](https://docs.stripe.com/rate-limits.md#handling-limiting-gracefully)).

- Um aumento repentino no volume de cobrança, como uma **Promoção flash**, pode resultar em limitação de fluxo. Tentamos definir nossos fluxos altos o suficiente para que o tráfego legítimo de pagamento nunca ultrapasse os limites, mas se você suspeitar que um evento no futuro próximo pode passar dos limites listados acima,[entre em contato com o Suporte da Stripe](https://support.stripe.com/).

- Emitir muitas solicitações de longa duração pode acionar a limitação de simultaneidade. As solicitações variam na quantidade de recursos do servidor da Stripe que consomem, e as solicitações mais intensivas em recursos podem demorar mais e correr o risco de fazer com que o limitador de simultaneidade descarte novas solicitações. Os requisitos de recursos variam bastante, mas as solicitações de listagem e as solicitações que incluem [expansões](https://docs.stripe.com/expand.md) geralmente consomem mais recursos e demoram mais para serem executadas. Sugerimos que você monitore a duração das solicitações da API da Stripe e observe os tempos limite para identificar aquelas que estejam inesperadamente lentas.

## Limitação de tratamento

Fique atento aos códigos de status `429` e implemente um mecanismo de novas tentativas para lidar com limitação de fluxo. Siga um cronograma de novas tentativas exponenciais para reduzir o volume de solicitações quando necessário e adicione aleatoriedade ao cronograma de novas tentativas para evitar um [efeito de manada](https://en.wikipedia.org/wiki/Thundering_herd_problem).

Uma abordagem mais sofisticada é controlar o tráfego para a Stripe em nível global e reduzi-lo se você detectar uma limitação significativa de taxa. Uma técnica comum para controlar o uso da API é implementar um [algoritmo de limitação de fluxo do tipo token bucket](https://en.wikipedia.org/wiki/Token_bucket) no lado do cliente. Implementações ou bibliotecas de bucket de token estão disponíveis para a maioria das linguagens de programação.

## Esgotamento de limites de tempo no bloqueio de objetos

As integrações podem encontrar erros com status HTTP `429`, código `lock_timeout` e a mensagem:

> Este objeto não pode ser acessado no momento porque outra solicitação de API ou processo da Stripe está acessando-o no momento. Caso veja esse erro aparecer de forma intermitente, tente novamente. Caso veja esse erro com frequência e esteja fazendo diversas solicitações simultâneas para um único objeto, faça suas solicitações em série ou em uma taxa menor.

A API da Stripe bloqueia determinados objetos em algumas operações para evitar que cargas de trabalho concorrentes interfiram entre si e gerem resultados inconsistentes. O erro acima ocorre quando uma requisição tenta adquirir um bloqueio que já está sendo mantido em outro lugar e acaba expirando por não conseguir obtê-lo a tempo. A Stripe não processa essas requisições que falham nesse estágio, o que significa que elas não recebem um [ID de requisição](https://docs.stripe.com/api/request_ids.md).

O esgotamento do limite de tempo dos bloqueios e a limitação de fluxo têm causas diferentes, mas suas mitigações são semelhantes. Assim como nos erros de limitação de fluxo, recomendamos fazer novas tentativas usando intervalos que aumentam exponencialmente (consulte [Processar limites corretamente](https://docs.stripe.com/rate-limits.md#handling-limiting-gracefully)). No entanto, ao contrário dos erros de limitação de fluxo, os mecanismos de novas tentativas automáticas das [SDKs](https://docs.stripe.com/sdks.md) da Stripe fazem novas tentativas para erros `429` causados por esgotamento do limite de tempo dos bloqueios:

#### Rubi

```ruby
Stripe.max_network_retries = 2
```

A contenção de bloqueios é causada pelo acesso simultâneo a objetos relacionados. Esse problema pode ser consideravelmente reduzido garantindo o enfileiramento e execução sequencial de mutações no mesmo objeto. Não há problema no uso de operações de API simultâneas, mas tente garantir que elas operem apenas em objetos únicos. Também é possível que a contenção de bloqueios seja causada por um conflito com um processo interno da Stripe em segundo plano. Isso deve ser raro, mas como esse problema está fora do controle do usuário recomendamos que todas as integrações possam fazer novas tentativas de solicitação.

## Testes de carga

É comum que os usuários se preparem para um grande evento de vendas testando a carga de seus sistemas, com o API Stripe em execução em uma área restrita como parte dele. Geralmente, desaconselhamos essa prática porque os limites da API são mais baixos em uma área restrita e, portanto, o teste de carga provavelmente atingirá limites que não atingiria em produção. Uma área restrita também não é um ambiente perfeito para chamadas de API ao vivo, e isso pode ser um pouco enganoso. Por exemplo, a criação de uma cobrança no modo de produção envia uma solicitação para um gateway de pagamento, e essa solicitação é simulada em uma área restrita, resultando em perfis de latência significativamente diferentes.

Outra opção recomendada é criar integrações com um sistema configurável, que você pode ativar para testes de carga, que simule solicitações à API Stripe. Para obter resultados realistas, esse sistema deve simular a latência, aguardando um tempo determinado por amostragens do tempo de resposta obtido pela integração em chamadas reais à API Stripe no modo de produção.

## Alocações de solicitação de leitura da API

A Stripe fornece acesso às suas solicitações de API de leitura (GET) para facilitar atividades de busca razoáveis relacionadas a integrações de pagamento. Para maximizar a qualidade de serviço para todos os usuários, a Stripe fornece as seguintes alocações para solicitações de leitura com base na contagem de transações:

- As requisições de leitura da API da sua conta não devem exceder uma média de 500 por transação. Por exemplo, se você processar 100 transações em 30 dias, não deve exceder 50.000 requisições de leitura de API durante esse período.

- Ao usar o Connect, uma plataforma e suas contas conectadas têm permissões de API de leitura distintas:

  - Cada conta conectada tem sua própria alocação para solicitações iniciadas por ela (500 solicitações por transação).
  - As plataformas Connect usam uma alocação separada para fazer solicitações de leitura em nome de suas contas conectadas usando sua chave de API secreta ou tokens de acesso OAuth. Essa alocação também é de 500 solicitações por transação com base na contagem agregada de transações em suas contas conectadas.

- Os índices são calculados ao longo de um período móvel de 30 dias (os 30 dias mais recentes).

- Cada conta, independentemente do número de transações, tem uma alocação mínima de 10.000 solicitações de leitura por mês.

- As solicitações da API de gravação não têm limite de alocação.

As chamadas para os seguintes endpoints de API estão excluídas dos limites de alocação acima:

- [Produtos de dados](https://docs.stripe.com/data.md)
- [Produtos dos relatórios](https://docs.stripe.com/stripe-reports.md)
- [Produtos fiscais](https://docs.stripe.com/tax.md)

Para reduzir o volume de solicitações da API, considere usar o [Data Pipeline](https://docs.stripe.com/data/data-pipeline.md) para realizar uma exportação completa dos dados da API para seu provedor ou banco de dados local.

> #### Filtrar solicitações para limitar chamadas paginadas
> 
> Alguns endpoints de lista retornam [várias páginas](https://docs.stripe.com/api/pagination.md) de resultados e podem exigir que várias solicitações retornem o conjunto completo de objetos de API para uma operação de lista. Aplique filtros quando possível para restringir os resultados da lista.