Limitações de fluxo

A API Stripe usa várias proteções contra picos de tráfego de entrada para ajudar a maximizar sua estabilidade. Se você enviar muitas solicitações em sequência, poderá ver respostas de erro com o código de status 429.

Limitadores de APIs

Temos vários limitadores na API, incluindo um limitador de fluxo e um limitador de simultaneidade.

Trate os limites como máximos e não gere carga desnecessária. Para evitar abuso, podemos reduzir os limites.

Para obter orientações sobre como gerenciar erros 429, consulte Gerenciar limitações corretamente. Se observar um aumento acentuado de solicitações com limitação de tempo, fale com o Suporte da Stripe.

Você pode solicitar um aumento de limite para habilitar um aplicativo de alto tráfego entrando em contato com o Suporte da Stripe. Se estiver solicitando um aumento considerável, entre em contato conosco com no mínimo 6 semanas de antecedência.

Limitação de fluxo

A limitação de fluxo básica restringe o número de solicitações de API por segundo da seguinte forma:

• Modo de produção: 100 operações de leitura e 100 operações de gravação
• Modo de teste: 25 operações de leitura e 25 operações de gravação

As chamadas para determinados recursos têm limites mais rígidos e também são consideradas nos limites básicos. Esses limites mais rígidos se aplicam separadamente aos modos de produção e teste.

• Arquivos de API: 20 operações de leitura e 20 operações de gravação por segundo
• API de pesquisa: 20 operações de leitura por segundo

As chamadas para o endpoint de eventos do medidor em modo de produção estão sujeitas a um limitador de fluxo separado e não são consideradas nos limites básicos. O limite é de 1000 chamadas por segundo por conta Stripe. No modo de teste, as chamadas para o endpoint de eventos do medidor são consideradas no limite básico. Nas plataformas Connect, as chamadas em uma conta conectada para o endpoint de eventos do medidor também são consideradas no limite básico.

Limitador de simultaneidade

O limitador de simultaneidade restringe o número de solicitações ativas simultâneas. Problemas com esse limitador são menos comuns do que com a limitação de fluxo, mas provavelmente indicam a existência de solicitações que usam muitos recursos e de longa duração.

As chamadas para o endpoint de eventos do medidor estão limitadas a uma chamada simultânea por cliente e por medidor.

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).
• A emissão de muitas solicitações com longo tempo de execução também pode acionar a limitação. As solicitações usam quantidades variáveis de recursos de servidor da Stripe. As que fazem uso mais intensivo de recursos tendem a demorar mais, o que aumenta o risco de novas solicitações serem recusadas pelo limitador de simultaneidade. Os requisitos de recursos variam bastante, mas solicitações de listagens ou que incluem expansões costumam usar mais recursos e demorar mais. Sugerimos que você crie perfis de duração das solicitações de API da Stripe e fique atento ao esgotamento de limites de tempo para detectar respostas mais demoradas que o esperado.
• Um aumento súbito no volume de cobrança, como uma oferta relâmpago pode resultar em limitação de fluxo. Tentamos definir taxas altas o suficiente para que o tráfego de pagamentos legítimos nunca exceda os limites, mas se você suspeitar que um evento futuro pode fazer com que exceda os limites listados acima, entre em contato com o Suporte da Stripe.

Processar limites corretamente

Uma técnica básica para o processamento correto de limites pelas integrações é monitorar a ocorrência do status 429 e criar um mecanismo de novas tentativas. Esse mecanismo deve usar intervalos que aumentem exponencialmente para reduzir o volume quando necessário. Também recomendamos incorporar um certo nível de aleatoriedade nos aumentos exponenciais para evitar o acionamento simultâneo de um grande número de eventos.

A otimização de solicitações individuais é limitada. Uma abordagem ainda mais sofisticada é controlar o tráfego global para a Stripe e reduzi-lo quando limitações de fluxo relevantes são observadas. Uma técnica comum de controle de taxa é implementar algo como um algoritmo de limitação de fluxo com token bucket no lado do cliente. Há implementações de token bucket prontas para uso e estáveis disponíveis para praticamente qualquer linguagem 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:

Não é possível acessar este objeto porque ele já está sendo acessado por outra solicitação de API ou processo da Stripe. Se esse erro ocorre de forma intermitente, envie a solicitação novamente. Se o erro ocorre com frequência e você está enviando várias solicitações simultâneas para o mesmo objeto, serialize as solicitações ou reduza sua taxa.

A API Stripe bloqueia objetos em algumas operações para que cargas de trabalho simultâneas não gerem interferências e resultados inconsistentes. O erro acima é causado por uma solicitação que tenta bloquear um objeto que já está bloqueado e esgota o limite de tempo antes de conseguir obter esse bloqueio.

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). No entanto, ao contrário dos erros de limitação de fluxo, os mecanismos de novas tentativas automáticas das SDKs da Stripe fazem novas tentativas para erros 429 causados por esgotamento do limite de tempo dos bloqueios:

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. Apesar de ser raro, esse problema está fora do controle do usuário. Por isso, 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 a API Stripe em execução no modo de teste. Geralmente, não recomendamos essa prática porque os limites da API são mais baixos no modo de teste. Portanto, é provável que o teste de carga atinja limites que não seriam alcançados no modo de produção. O modo de teste também não é um substituto perfeito para as chamadas de API em produção, podendo ser um pouco enganoso. Por exemplo, uma cobrança criada no modo de produção envia uma solicitação a um gateway de pagamentos, e essa solicitação é simulada no modo de teste, 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 de 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 solicitações de API de leitura não devem exceder uma proporção média de 500 solicitações por transação para uma conta. Por exemplo, se uma conta processa 100 transações em um período de 30 dias, ela não deve exceder 50.000 solicitações de API de leitura durante o mesmo 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.
• As proporções são medidas em uma base de 30 dias consecutivos.
• 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
• Produtos dos relatórios
• Produtos fiscais

Para reduzir o volume de solicitações de API, considere usar o Stripe Data Pipeline para uma exportação completa de dados de API para seu banco de dados ou provedor local.