A API possui três tipos de limite. Quando um limite aplicável é ultrapassado, a requisição retorna HTTP 429 Too Many Requests.
| Limite | Regra |
|---|---|
| Rate limit | Frequência permitida em determinados endpoints |
| Cota | Até 25.000 requisições por conta a cada 12 horas |
| Concorrência | Até 50 requisições GET simultâneas |
Rate limit
Determinados endpoints possuem limites próprios de frequência.
Consulte os headers da resposta para acompanhar o consumo:
RateLimit-Limit: 100
RateLimit-Remaining: 50
RateLimit-Reset: 30| Header | Descrição |
|---|---|
RateLimit-Limit | Quantidade de requisições permitidas no período |
RateLimit-Remaining | Quantidade de requisições restantes |
RateLimit-Reset | Segundos restantes até a liberação do limite |
Quando RateLimit-Remaining chegar a 0, novas requisições podem retornar HTTP 429 Too Many Requests. Aguarde o período indicado em RateLimit-Reset antes de tentar novamente.
Limite de cota
Cada conta pode realizar até 25.000 requisições em um período de 12 horas, independentemente dos endpoints utilizados.
A janela começa na primeira requisição. As chamadas realizadas nas 12 horas seguintes são contabilizadas nessa cota. Após esse período, o contador é reiniciado.
Ao atingir o limite, a API retorna HTTP 429 Too Many Requests.
Limite de requisições concorrentes
Uma requisição é considerada concorrente quando é enviada antes que uma requisição anterior tenha sido respondida.
A API permite até 50 requisições GET concorrentes por conta.
As chamadas que ultrapassarem esse limite retornam HTTP 429 Too Many Requests.
Como tratar o erro 429
Identifique qual limite foi atingido pela mensagem no corpo da resposta. Os headers RateLimit-* não identificam qual limite foi atingido.
| Limite | Mensagem no corpo da resposta | Headers RateLimit-* | Como tratar |
|---|---|---|---|
| Concorrência | "Limite de requisições concorrentes atingido: N" | Não | Reduza a quantidade de requisições GET simultâneas. |
| Cota de 12 horas | "Cota de requisições das últimas N horas excedida." | Sim | Reduza chamadas não essenciais e aguarde a renovação da cota. |
| Rate limit do endpoint | "Seu acesso foi temporariamente bloqueado..." | Sim | Aguarde o período indicado em RateLimit-Reset. |
Como a cota e o rate limit do endpoint retornam os mesmos headers RateLimit-*, utilize a mensagem para diferenciá-los.
O header Retry-After não é enviado em respostas 429. Ele é enviado somente quando o acesso é bloqueado temporariamente com HTTP 403 Forbidden.
Não execute retries imediatamente após uma resposta 429.
Para diagnóstico e estratégias de controle de tráfego, consulte Requisições bloqueadas por ausência de controle de limites.
RecomendadoNão utilize consultas
GETrecorrentes para acompanhar mudanças de estado quando existir um Webhook correspondente.Use Webhooks para receber as alterações e consultas
GETquando precisar recuperar o estado atual de um recurso.