Limites de uso

A API aplica três limites independentes. Cada um responde 429, com um code diferente, para você saber o que ajustar.

Limite	Escopo	Código no 429
Taxa de requisições	Por conta, separado por classe de operação	`rate_limit_exceeded`
Requisições simultâneas	Por conta	`concurrency_limit_exceeded`
Falhas de autenticação	Por IP de origem	`auth_failure_limit_exceeded`

Taxa de requisições

O limite de taxa é por conta e vale para todas as chaves dela somadas. Trocar de chave não aumenta o teto. As operações são contadas em duas classes separadas, cada uma com seu próprio orçamento:

Classe	Operações
Escrita de validações	Os três `POST /validations/*`
Leitura	`GET /validations`, `GET /validations/{id}` e todos os endpoints de Chaves de API

O orçamento funciona como um balde: ele acumula folga quando você fica abaixo do ritmo, o que permite picos curtos, e se recompõe continuamente. Estourar a taxa de leitura não afeta o seu orçamento de criação de validações. Para conhecer o teto da sua conta ou pedir um aumento, fale com o suporte.

Requisições simultâneas

Independente da taxa, há um teto de requisições em voo ao mesmo tempo por conta. Uma integração que dispara centenas de validações em paralelo pode bater nele mesmo respeitando a taxa. A saída é limitar a concorrência do seu lado, com uma fila ou um pool.

Falhas de autenticação

Requisições que terminam em 401 são contadas por IP de origem. Depois de várias seguidas, o IP recebe 429 com auth_failure_limit_exceeded por um tempo. Só o que falha conta. Tráfego com chave válida nunca entra nessa contagem, então volume legítimo vindo de um IP compartilhado não é penalizado.

Cabeçalhos da resposta

Os cabeçalhos aparecem na resposta 429, não nas bem-sucedidas.

Cabeçalho	Descrição
`Retry-After`	Segundos a esperar antes de tentar de novo. Vem em todo `429`.
`RateLimit-Limit`	Teto da classe para a sua conta.
`RateLimit-Remaining`	Quanto resta na janela atual.
`RateLimit-Reset`	Segundos até o orçamento se recompor por completo.

Os três cabeçalhos RateLimit-* só vêm no 429 de taxa. O 429 de concorrência e o de falhas de autenticação trazem apenas Retry-After, porque nenhum dos dois descreve um orçamento por janela.

Como tratar um 429

Leia Retry-After e espere esse tempo. É a única fonte confiável, em qualquer um dos três casos.
Repita com espera exponencial e um pouco de aleatoriedade, para não sincronizar todas as retentativas no mesmo instante.
Se for um POST de validação, reenvie com o mesmo Idempotency-Key. Uma requisição barrada no 429 nunca foi cobrada, e a chave garante que uma eventual retentativa duplicada também não seja.

async function comRetentativa(requisicao, tentativas = 5) {
  for (let tentativa = 0; tentativa < tentativas; tentativa++) {
    const resposta = await requisicao();
    if (resposta.status !== 429) return resposta;

    const espera = Number(resposta.headers.get("Retry-After") ?? 1);
    const jitter = Math.random();
    await new Promise((r) => setTimeout(r, (espera + jitter) * 1000));
  }
  throw new Error("limite de requisições persistente");
}

Saldo insuficiente responde 402 com insufficient_balance, não 429. Repetir não resolve: recarregue a conta no painel.

Referência da API

Validações

Chaves de API

Taxa de requisições

Requisições simultâneas

Falhas de autenticação

Cabeçalhos da resposta

Como tratar um 429

​Taxa de requisições

​Requisições simultâneas

​Falhas de autenticação

​Cabeçalhos da resposta

​Como tratar um 429

Taxa de requisições

Requisições simultâneas

Falhas de autenticação

Cabeçalhos da resposta

Como tratar um 429