Limites de taxa

Limites por chave, como eles são sinalizados e como tratar respostas 429 corretamente.

A WASViking^® aplica limites de taxa (rate limits) por chave de API. Os limites são dimensionados para o uso operacional normal e documentados por classe de endpoint.

Limites padrão

Headers

Toda resposta inclui:

Quando a requisição sofre throttling:

Como tratar o 429 corretamente

• Respeite o Retry-After. Não tente de novo antes disso.
• Use backoff exponencial com jitter em respostas 429 repetidas.
• Faça cache das respostas de leitura idempotentes sempre que puder.
• Agrupe. A maioria dos consumidores faz muitas leituras pequenas que poderiam ser uma única consulta paginada.

Uma política de retentativa razoável, em pseudocódigo:

delay = float(headers.get("Retry-After", 30))
for attempt in range(5):
    sleep(delay + random.uniform(0, 0.5 * delay))
    response = call_api()
    if response.status_code != 429:
        return response
    delay *= 2
raise RetryExceeded()

Limites de concorrência

O limite de 12 scans simultâneos é por organização, não por chave. Se você executa vários pipelines de CI contra a mesma organização, planeje-se para isso. O portal mostra a concorrência atual em Settings → API Usage.

Quando o limite é atingido e você chama POST /scans, a API:

1. Aguarda até 60 segundos para que uma vaga se abra.
2. Se uma vaga se abrir, aceita o scan e retorna 201 Created.
3. Se nenhuma vaga se abrir, retorna 429 com Retry-After.

No sentinel ci, isso aparece como exit code 77 (scan_capacity).

Medição mensal

Alguns planos medem:

• AI Recommendations por mês.
• Scans por mês.
• Envios de SBOM por mês.

Quando a medição se esgota em um escopo medido, a API retorna 403 com error: "metered". O portal mostra o estado atual da medição em Settings → API Usage e em Billing → Usage.

O sentinel ci apresenta isso como exit code 78.

Como aumentar os seus limites

Os limites podem ser aumentados por organização quando há necessidade operacional contínua. Abra uma solicitação em Settings → API Usage → Request increase ou escreva para [email protected]. Inclua:

• A classe de endpoint e o novo valor pretendido.
• O QPS de pico e o QPS médio que você espera.
• Uma justificativa curta.

Aprovamos aumentos que correspondem ao uso real. Recusamos pedidos genéricos do tipo "remover todos os limites".

O que os limites NÃO são

• Eles não são uma cota rígida da organização (exceto a medição mensal, que é explícita).
• Eles não são por usuário; são por chave.
• Eles não são aplicados na borda, separadamente da aplicação. Quem os aplica é a stack de aplicação da WASViking; a borda da Cloudflare mantém um piso separado, bem mais alto, contra abuso nos endpoints públicos.