Os limites de taxa da API da Pinnacle são um orçamento, não um muro.

Como é uma resposta de limite da API da Pinnacle

Exceda a cota por segundo e a API retorna HTTP 429 Too Many Requests, normalmente com um header Retry-After que diz quantos segundos esperar antes da próxima tentativa:

HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/json

Trate o 429 como um sinal, não como uma exceção. Registre cada ocorrência com seu timestamp e a chamada que o disparou: uma contagem crescente de 429 é um alerta antecipado de que a carga em regime está derivando para o teto. O Retry-After é a autoridade. Quando presente, ele se sobrepõe a qualquer agenda que seu cliente tinha em mente, e insistir através de um 429 sem esperar é como um limite transitório vira um estrangulamento mais longo.

Backoff que funciona

O padrão é backoff exponencial com jitter: espere um atraso base, dobre-o após cada rejeição, limite-o e adicione aleatoriedade para que workers paralelos não tentem de novo em sincronia.

delay = 0.5        # seconds
max_delay = 30
loop:
    res = get(url)
    if res.status != 429:
        return res
    wait = res.headers["Retry-After"] ?? delay
    sleep(wait + random(0, wait / 2))
    delay = min(delay * 2, max_delay)

Três regras fazem isso funcionar em produção. Sempre respeite o Retry-After quando o header existir, porque o servidor conhece sua própria janela melhor do que a sua estimativa. Limite o total de tentativas e falhe o ciclo em vez de bloquear o próximo; as odds estarão mais frescas em cinco segundos de qualquer forma. Compartilhe o estado de backoff entre workers, porque dez processos recuando educadamente ainda somam dez vezes as requisições.

Projetando a folga

Backoff é triagem; folga é prevenção. Mantenha o uso em regime abaixo de cerca de 70 por cento da cota por segundo. Em um nível de 10 requisições por segundo isso significa ritmar o polling regular em 7 por segundo ou menos, e reservar o resto para retentativas, ferramentas administrativas e um segundo ambiente.

Dias de jogo são o teste. Requisições de quadro ficam estáveis quando a rodada cresce, mas chamadas de detalhe por evento, retentativas e rajadas de reconexão não, como mostra o planejamento de capacidade, e as primeiras respostas 429 tendem a chegar durante as maiores rodadas, quando dados defasados custam mais. Se sua estimativa de pico fica em 80 ou 90 por cento do teto, a resposta é um nível maior ou um escopo menor, não retentativas mais apertadas. Os níveis comparados neste site diferem principalmente na taxa por segundo, que é exatamente a dimensão onde a folga vive.

Ver planos de capacidade

Quando o polling deixa de escalar

O custo do polling cresce linearmente com a atualidade: reduza o intervalo pela metade e você dobra as requisições, em todos os quadros que consulta, o dia inteiro. A partir de certo ponto a curva deixa de fazer sentido. Se seu produto precisa de percepção abaixo de 2 segundos em uma rodada completa, polling REST é a ferramenta errada para o caminho crítico.

A alternativa é push em vez de pull. Alertas de queda via SSE transmitem mudanças de odds processadas conforme acontecem, enquanto o REST continua para o bootstrap e a reconciliação periódica. O poller pede um snapshot; o stream diz o que acabou de se mover, e os limites por segundo em grande parte deixam de ser seu problema.

A disciplina de polling em integração REST eficiente continua valendo para o lado REST dessa divisão, e a comparação de planos mostra quais níveis incluem o stream.

Um loop que já trata o 429 do jeito que esta página descreve está no quickstart de Node.js no pnclFEED, onde o Retry-After define a espera.

Obter acesso à API