Limites de requisição

A API aplica limites em duas camadas: uma proteção por origem antes da autenticação e um limite contratual por conta depois que a API Key é validada.

Limites atuais

Camada	Limite	Escopo
Proteção de origem	1.200 requisições por minuto	Por IP; endereços IPv6 são agrupados por `/64`
Conta padrão	30 requisições por minuto	Compartilhado por todas as API Keys e todos os IPs da conta
Conta com limite contratado	Valor configurado no plano ou override da conta	Compartilhado por todas as API Keys e todos os IPs da conta

O limite por conta usa uma janela fixa de 60 segundos. Criar outra API Key não aumenta a franquia.

O valor contratual pode ser superior ao padrão. Confirme o limite da sua conta durante a habilitação comercial da API.

Headers

Em respostas autenticadas, os headers representam o limite efetivo da conta:

Header	Significado
`X-RateLimit-Limit`	Total de requisições permitido na janela atual
`X-RateLimit-Remaining`	Requisições ainda disponíveis; nunca fica negativo
`X-RateLimit-Reset`	Segundos até a virada da janela
`Retry-After`	Segundos que devem ser aguardados; aparece no `429`

Exemplo de limite esgotado:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "This account exceeded 30 API requests per minute."
  }
}

X-RateLimit-Reset e Retry-After usam segundos, não timestamp Unix. Quando a credencial ainda não foi autenticada, uma resposta de bloqueio pode trazer os headers da proteção por origem, pois a conta ainda não é conhecida.

Estratégia recomendada

Respeite Retry-After quando ele existir.

Caso não exista, use backoff exponencial com jitter.

Mantenha a mesma Idempotency-Key ao repetir uma operação.

Limite a concorrência no seu lado.

Use webhooks em vez de consultar repetidamente o estado do envelope.

Exemplo em JavaScript:

Falha do contador

Se o serviço responsável pela contagem estiver indisponível, a API responde 503 em vez de continuar sem proteção. Repita com backoff e, em operações POST, preserve a mesma Idempotency-Key.

O que não deve ser feito

Não crie várias chaves para tentar multiplicar o limite.

Não faça polling em intervalos curtos.

Não troque a chave de idempotência ao receber 429, timeout ou 503.

Não use o texto de message como regra de negócio; use status HTTP e error.code.

Não distribua tráfego entre IPs para contornar a proteção.

Limites atuais#

Headers#

Estratégia recomendada#

Falha do contador#

O que não deve ser feito#

Limites atuais

Headers

Estratégia recomendada

Falha do contador

O que não deve ser feito