Limites de chamadas à API de brokers exigem filas, orçamentos e backoff

Engenheiro de operações consulta um dashboard de trading durante um incidente de limite de chamadas na API de um broker
Photo by Rafael Minguet Delgado on Pexels

Às 16:42 de sexta-feira, um líder de operações olha para um dashboard que está no vermelho há quase toda a semana. As confirmações de ordens estão atrasadas, os painéis de dados de mercado têm lacunas e a taxa de erros da API passou de 8 per cento.

O broker está acessível. Os próprios clientes da empresa estão fazendo chamadas demais ao mesmo tempo.

Este incidente composto é típico de um sistema com credenciais compartilhadas sob carga, não é o relato dos resultados de uma empresa específica. Quatro serviços usam a mesma chave de API do broker: um aplicativo web, um monitor de posições, um exportador de histórico e um worker de reconciliação.

Na abertura do mercado, cada um repete as solicitações assim que recebe HTTP 429. Em vez de deixar a taxa de solicitações cair, as novas tentativas mantêm o limite compartilhado esgotado.

O dashboard de sexta-feira: um limite compartilhado por quatro serviços

Reconstrua o orçamento real

A análise do incidente começa pela documentação de cotas do broker e pelos cabeçalhos das respostas, não por uma mudança no timeout do cliente. Suponha que a conta tenha uma franquia documentada de 1,200 solicitações por minuto e capacidade de pico de cerca de 80 solicitações. Esses números são ilustrativos. Os provedores podem aplicar cotas diferentes por conta, credencial, endpoint, nível de produto ou endereço IP, e podem alterá-las sem mudar o limite divulgado.

Às 09:30, os quatro serviços fazem cerca de 280 solicitações em três segundos. A camada web contribui com atualizações de cotações e posições; o exportador de histórico executa uma tarefa de atualização; o monitor consulta contas que não mudaram; e a reconciliação faz suas chamadas programadas. Um bucket de pico com capacidade para 80 solicitações pode se esvaziar rapidamente, mesmo que o total do minuto ainda caiba na franquia documentada. As novas tentativas imediatas e repetidas acrescentam tráfego justamente quando a capacidade está escassa.

Antes de ajustar os parâmetros, colete os seguintes dados por pelo menos um período de pico:

  • Contagem de solicitações por credencial, endpoint, serviço e código de resposta.
  • Respostas 429, valores de Retry-After e cabeçalhos de limite de chamadas ou reset, quando fornecidos.
  • Concorrência de solicitações, latência, timeouts e idade do trabalho em fila.
  • Se várias instâncias do aplicativo compartilham a mesma cota ou usam limitadores locais independentes.

Use um relógio monotônico para intervalos locais, registre o horário de reset do broker quando disponível e sincronize os relógios dos hosts. Uma resposta 429 sem cabeçalho de reset ainda é uma evidência útil. Acompanhe-a junto com a solicitação que a provocou e o tráfego total da credencial. Quem acompanha a cobertura de infraestrutura de trading reconhecerá a questão operacional mais ampla: os limites dos endpoints fazem parte do planejamento de capacidade, não são um detalhe do tratamento de exceções.

Separe o volume de chamadas da demanda dos usuários

Um usuário que abre uma página de posições não precisa necessariamente de uma nova chamada REST para cada linha. O aplicativo pode exibir um snapshot recente, assinar atualizações por streaming quando a API permitir ou agrupar vários instrumentos em uma solicitação. Mas reduzir chamadas indiscriminadamente pode deixar os controles de risco desatualizados. Decida quais dados podem sofrer atraso e de quanto, e então deixe esse compromisso claro para os serviços a jusante.

A tabela apresenta faixas típicas de mercado para planejamento, não franquias garantidas. A unidade e o escopo importam: uma franquia por chave compartilhada entre réplicas não é uma franquia por processo.

Operação de APIFaixa típicaEscopo ou restrição comum
Cotações ou snapshots REST30-600 solicitações por minutoPor chave ou conta, às vezes com um bucket de pico de 5-30 chamadas
Barras históricas ou negócios10-120 solicitações por minutoEm geral, abaixo dos limites de cotações, com 2-10 tarefas simultâneas
Envio, cancelamento ou alteração de ordens5-30 solicitações por segundoPode ser separado por operação, conta ou sessão de trading
Assinaturas de streaming100-1,000 símbolos por conexãoO número de conexões e as alterações nas assinaturas podem ter limites separados

Essas faixas variam bastante conforme o broker, o acesso à bolsa e o nível comercial. Confirme se a cota contabiliza chamadas com falha, se os itens de uma chamada em lote são contados individualmente e se as ações de ordens têm um teto separado de controle de risco. Não deduza a capacidade de streaming a partir de uma cota REST.

Implemente um controlador no cliente antes de adicionar novas tentativas

Use um agendador por credencial

É comum cada processo ter seu próprio limitador, o que pode causar falhas. Quatro réplicas configuradas para 20 solicitações por segundo cada podem enviar 80 solicitações por segundo usando uma única credencial compartilhada. Coloque o orçamento em um ponto compartilhado por todos os chamadores: um gateway central de API, um token bucket distribuído ou um único worker de fila para cada credencial e classe de endpoint.

Um token bucket é útil quando o broker permite picos curtos além de uma taxa sustentada. Defina a taxa de reposição abaixo do limite documentado e reserve parte da capacidade para chamadas operacionais. Para um limite nominal de 1,200 solicitações por minuto, um orçamento inicial de taxa sustentada poderia ser de 15-18 por segundo, em vez do limite teórico de 20. Uma capacidade de pico de 30-50 solicitações dá margem para uma ação legítima de usuário sem permitir que uma tarefa em lote consuma todo o orçamento da conta.

Separe as filas conforme a consequência e a atualidade dos dados. Envios e cancelamentos de ordens, além de ações para reduzir risco, não devem ficar atrás de uma carga histórica. Cotações e posições podem ter metas diferentes de atualização. Um projeto típico poderia definir uma meta de fila de 100-300 ms para ações interativas com ordens, 1-3 segundos para atualizações rotineiras de posições e segundos ou minutos para tarefas com dados históricos. Esses são pontos de partida para testes, não níveis de serviço universais.

Defina limites explícitos para as filas. Uma fila sem limite transforma um evento de restrição de chamadas em trabalho atrasado que chega quando já não é útil. Quando a fila estiver cheia, agrupe leituras duplicadas, descarte atualizações vencidas, pause tarefas em lote ou retorne uma mensagem clara de degradação do serviço. Não descarte silenciosamente um comando de ordem.

Faça novas tentativas com segurança

Em uma resposta 429, respeite o Retry-After, se estiver presente. Se a resposta informar um horário de reset, agende as chamadas para esse momento com uma pequena variação aleatória, para que todos os workers não sejam ativados juntos. Sem nenhum desses cabeçalhos, use backoff exponencial com jitter completo. Uma sequência inicial prática é um atraso aleatório de 0-250 ms, depois 0-500 ms e, em seguida, 0-1 segundo, com limite de 5-10 segundos. Defina um pequeno orçamento de novas tentativas, como três tentativas para uma leitura, em vez de repetir indefinidamente.

Classifique as chamadas antes de repetir:

  • Repita leituras idempotentes após um atraso limitado, respeitando o prazo de atualidade definido pelo chamador.
  • Use uma chave de idempotência para envios de ordens, se a API oferecer suporte.
  • Se uma solicitação de ordem expirar após o envio, consulte o estado da ordem antes de reenviá-la. O servidor pode tê-la aceitado mesmo que a confirmação tenha sido perdida.
  • Não repita erros de validação ou de permissão como se fossem erros de capacidade.

O backoff controla a pressão, mas não resolve a ambiguidade sobre o estado da ordem. A camada de gerenciamento de ordens precisa de uma máquina de estados que represente os estados enviada, confirmada, rejeitada, expirada e pendente de reconciliação.

É aqui que uma política de novas tentativas encontra o risco de trading. Uma chamada GET duplicada de dados de mercado desperdiça capacidade; uma ordem duplicada pode criar exposição.

O backoff precisa distinguir atraso de recuperação

Uma resposta 429 informa que o chamador excedeu um limite. Ela não informa se toda a API está indisponível, se há restrição em um endpoint específico ou se uma cota por minuto será renovada em breve. Acompanhe as restrições por endpoint e credencial e compare-as com erros 5xx, timeouts de rede e latência. Esses sinais exigem respostas diferentes.

Quando as restrições aumentarem, reduza primeiro o tráfego opcional. Pause exportações de histórico, diminua a frequência das consultas de contas em segundo plano e exiba valores em cache dentro do prazo de validade permitido. Preserve capacidade para verificações do estado de ordens e ações para reduzir risco. Se o broker oferecer limites separados para ordens e dados de mercado, aplique orçamentos separados. Se usar um único pool compartilhado, reserve uma parcela para ordens e confronte a alocação real com os cabeçalhos observados e a documentação do suporte.

A recuperação exige uma retomada gradual, não uma reinicialização simultânea. Após a janela de reset, libere o trabalho em fila dentro do orçamento normal e aumente-o com cautela se a taxa de 429 permanecer baixa.

Um circuit breaker pode impedir que um endpoint com falhas receba mais chamadas, mas não deve bloquear outras classes de endpoint sem evidências de que compartilham a mesma falha. Gere alertas sobre a idade da fila e o tempo de dados desatualizados, além do percentual bruto de erros. Uma taxa de 429 de 0.2 per cent ainda pode ser importante se afetar todas as confirmações de ordens na abertura.

Teste o projeto com um perfil de carga semelhante ao do sistema real: atualizações programadas, picos de usuários, reconexões após uma interrupção de rede e uma tarefa em lote iniciada ao mesmo tempo. Inclua respostas do broker com e sem cabeçalhos de limite de chamadas.

Verifique se réplicas independentes compartilham o orçamento, se reinicializações não reabastecem um bucket de pico local e se o timeout de uma ordem não provoca uma duplicata às cegas. O material sobre tecnologia de brokers oferece contexto útil, mas os limites que prevalecem devem vir do provedor da API e das medições da própria empresa.

Comprove a política sob carga e, depois, defina regras de interrupção

Antes da implantação, defina como deve ser uma política saudável de controle de chamadas. Por exemplo, uma empresa pode buscar manter o uso sustentado abaixo de 80-90 per cent da franquia observada, manter a latência interativa da fila abaixo da meta de serviço e evitar que o trabalho em segundo plano atrase operações de ordens. Escolha os limites com base na cota real do broker e nos controles de risco da empresa, não em um modelo genérico de dashboard.

Faça um teste controlado com 1.2-1.5 vezes o pico de tráfego esperado, limitando o teste a um ambiente seguro ou a uma conta aprovada. Verifique se o excesso de leituras entra na fila ou tem a carga reduzida, se as ações de ordens mantêm a capacidade reservada e se a recuperação não cria um segundo pico. Revise estas medidas operacionais após cada lançamento:

  1. Taxa de 429 e taxa total de solicitações, separadas por endpoint, credencial e serviço.
  2. Profundidade da fila, idade do item mais antigo, leituras descartadas ou agrupadas e número de novas tentativas.
  3. Latência das confirmações de ordens, envios não resolvidos e verificações de ordens duplicadas.
  4. Atualidade dos dados de cotações, posições e estado da conta durante a operação degradada.

Designe um responsável por mudanças nas cotas e documente o caminho de escalonamento do provedor. Se a empresa precisar de mais capacidade, pergunte se o provedor pode aumentar o limite, separar credenciais por carga de trabalho ou oferecer uma alternativa por streaming ou em lote. Adicionar chaves para contornar um limite compartilhado da conta pode violar os termos e dificultar a análise de incidentes. Trate o aumento da cota como uma opção, não como substituto de um modelo de tráfego.

Pare de fazer o seguinte:

  • Repetir imediatamente toda resposta 429.
  • Dar a cada réplica uma cópia independente da mesma cota.
  • Colocar cargas históricas na mesma fila que as ações de ordens.
  • Reenviar ordens expiradas sem verificar seu estado.

Perguntas frequentes

O que um cliente de API de trading deve fazer após receber HTTP 429?

Respeite o Retry-After ou o cabeçalho de reset do provedor e, se a resposta não indicar o momento, repita com jitter. Limite as tentativas e reduza o tráfego opcional enquanto a credencial estiver sob restrição.

Os limites de chamadas da API do broker devem ser compartilhados entre réplicas do aplicativo?

Sim, se o broker aplicar a cota a uma chave, conta ou endereço IP compartilhado. Use um agendador central ou um limitador distribuído para manter o tráfego combinado dentro de um único orçamento.

É seguro repetir uma solicitação de ordem que expirou?

Não sem verificar. O broker pode ter aceitado a ordem mesmo que a confirmação tenha sido perdida. Consulte o estado da ordem primeiro ou use uma chave de idempotência compatível antes de reenviá-la.