Limitações de fluxo

Utilizamos mecanismos de proteção contra picos de tráfego para maximizar a estabilidade da API. Se você enviar muitas solicitações em rápida sucessão, poderá receber respostas de erro 429.

Limitadores de API

Aplicamos vários limitadores de API, incluindo limitadores de taxa e de simultaneidade. Trate os limites como máximos e evite carga desnecessária. Para prevenir abusos, podemos reduzir seus limites. Para obter orientações sobre como lidar com erros 429, consulte Como tratar limitações de forma adequada. Se você notar um aumento em solicitações com limitação de fluxo, entre em contato com o Suporte da Stripe.

Solicite um aumento do limite para aplicativos de alto tráfego por meio do Suporte da Stripe. Se você for solicitar um grande aumento,entre em contato com o Suporte da Stripe com pelo menos seis semanas de antecedência.

Limitador 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
• Sandbox: 25 operações

As chamadas para recursos individuais têm limites mais rígidos e também são consideradas nos limites globais. Endpoints de API têm um limite padrão de 25 solicitações por segundo. A Stripe pode aumentar os limites de taxa para contas específicas com base no uso.

• API Payment Intents: 1000 operações de atualização por PaymentIntent, por hora
• API Files: 20 operações de leitura e 20 operações de gravação por segundo.
• API Search: 20 operações de leitura por segundo.
• API Subscriptions:
  • 10 novas faturas por assinatura, por minuto
  • 20 novas faturas por assinatura, por dia
  • 200 atualizações de quantidade por assinatura, por hora
• Criar API Payout: 15 solicitações por segundo e 30 solicitações simultâneas por comerciante.
• Connect: as plataformas podem criar até cinco contas por segundo na área restrita e 30 contas por segundo no modo de produção.
• Emissão: a criação de cartão tem limites de fluxo que dependem do país e do setor da empresa.

As chamadas para o endpoint de eventos de medidor no modo de produção estão sujeitas a um limite de taxa separado e não são consideradas em relação aos limites básicos. O limite é de 1000 chamadas por segundo por conta Stripe. Em uma área restrita, as chamadas para o endpoint de eventos de medidor contam para o limite básico. Para plataformas Connect, as chamadas em uma conta conectada para o endpoint de eventos de medidor também contam para o limite básico.

Solicitações com limitação de fluxo

Solicitações com limitação de taxa retornam o cabeçalho Stripe-Rate-Limited-Reason com valores que indicam qual limite de taxa a solicitação você excedeu. Os valores possíveis para esse cabeçalho são:

• global-concurrency: suas solicitações excederam o limite de simultaneidade global. Você pode evitar isso enviando menos solicitações simultâneas.
• global-rate: suas solicitações excederam o limite de taxa global. Você pode evitar isso enviando solicitações a uma taxa reduzida.
• endpoint-concurrency: suas solicitações para este endpoint de API específico excederam o limite de simultaneidade. Você pode evitar isso enviando menos solicitações simultâneas para esse endpoint específico.
• endpoint-rate: suas solicitações para este endpoint de API específico excederam o limite de taxa. Você pode evitar isso enviando solicitações para esse endpoint a uma taxa reduzida.
• resource-specific: você atingiu um limite de taxa relacionado 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 limitador de taxa (por exemplo, pode ser um tempo limite de bloqueio).

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).

• Enviar várias solicitações de longa duração pode acionar limites. As solicitações variam na quantidade de recursos dos servidores da Stripe que utilizam, e as mais intensivas em recursos podem demorar mais e correr o risco de fazer com que o limitador de concorrência descarte novas solicitações. Os requisitos de recursos variam bastante, mas solicitações de listagem e solicitações que incluem expansões geralmente usam mais recursos e levam mais tempo para serem executadas. Sugerimos analisar a duração das solicitações à API da Stripe e monitorar timeouts para identificar aquelas que estão inesperadamente lentas.

• 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.

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.

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:

Este objeto não pode ser acessado no momento porque outra solicitação de API ou processo da Stripe está acessando-o. Se esse erro ocorrer de forma intermitente, tente novamente a solicitação. Se esse erro ocorre com frequência e você faz várias solicitações simultâneas para um único objeto, faça suas solicitações em série ou com uma taxa reduzida.

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.

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. 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
• 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.