Limitações de fluxo
A API Stripe usa diversas proteções contra picos de tráfego de visitas para ajudar a maximizar o sistema. Os usuários que enviam muitas solicitações em uma sucessão rápida podem receber erros com código de status 429
. Temos vários limitadores na API, incluindo:
Um limitador de fluxo que restringe o número de solicitações recebidas pela API em um determinado segundo.
Para a maioria das APIs, a Stripe permite até 100 operações de leitura e 100 operações de gravação por segundo no modo de produção. No modo de teste, o limite é 25 para os dois tipos de operação.
Para a API Files, a Stripe permite até 20 operações de leitura e 20 operações de gravação por segundo nos modos de teste e produção. Os limites desses dois modos são separados.
Para a API Search, a Stripe permite até 20 operações de leitura por segundo para todos os endpoints de pesquisa nos modos de teste e produção. Os limites desses dois modos são separados.
Um limitador de simultaneidade que restringe o número de solicitações ativas em um determinado momento. Os problemas com esse limitador são menos comuns que os do limitador de fluxo de solicitações, mas é mais provável que resultem em solicitações de longa duração e com uso intensivo de recursos.
Trate esses limites como valores máximos e não gere cargas desnecessárias. Consulte Processar limites corretamente para obter orientações sobre como lidar com os erros 429. Se você notar um aumento súbito de solicitações com limitação de fluxo, fale com o suporte.
Podemos reduzir os limites para evitar abusos ou aumentá-los para habilitar aplicativos de alto tráfego. Para solicitar um aumento na limitação de fluxo, fale com o suporte. Se você estiver solicitando um aumento grande, entre em contato conosco com seis semanas de antecedência.
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 do volume de cobranças, como em uma oferta relâmpago, pode acionar a limitação de fluxo. Tentamos definir fluxos altos para não limitar o tráfego legítimo de pagamentos da grande maioria dos usuários. No entanto, se você acredita que um próximo evento pode exceder os limites acima, fale com o suporte.
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 bibliotecas de cliente da Stripe fazem novas tentativas para erros 429
causados por esgotamento do limite de tempo dos bloqueios:
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:
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.
Filtrar solicitações para limitar chamadas paginadas
Alguns endpoints de lista retornam várias páginas 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.