Limites e cota
Valores
| Limite | Valor padrão | Vale para |
|---|---|---|
| Por chave | 60 requisições por minuto | cada chave de API |
| Por organização | 120 requisições por minuto | todas as chaves da organização somadas |
| Cota mensal | 50.000 requisições por mês | a organização |
| Por endereço IP | 300 requisições por minuto | qualquer requisição, antes de conferir a chave |
| Itens por página | 50 (padrão), até 100 | listas |
| Tamanho do corpo | 256 KB | POST e PATCH |
Os valores em vigor para a sua organização aparecem no painel e na rota /v1/me. Se precisar de limites maiores, fale com o suporte.
A cota mensal
- A cota renova no dia 1º de cada mês, às 00:00 UTC (21:00 do último dia do mês, no horário de Brasília).
- A cota não usada não passa para o mês seguinte.
- O dono e os administradores recebem um e-mail quando a organização usa 80% e 100% da cota.
O que conta na cota
Cada requisição autenticada que chega a ser processada conta 1, seja leitura ou escrita, inclusive as que terminam em erro por dados inválidos ou falta de escopo (403 insufficient_scope, 404, 409, 412, 422) e as respostas 304.
Não contam:
- requisições recusadas por limite ou cota (
429); - requisições sem chave válida (
401); - requisições recusadas por falta de acesso, de assinatura ou de aceite dos termos (
402e os403de acesso:api_access_not_enabled,api_access_suspended,workspace_not_eligible,terms_not_accepted); - falhas do Validades (
5xx).
Cabeçalhos de limite
Toda resposta autenticada informa a situação dos limites:
| Cabeçalho | Significado |
|---|---|
RateLimit-Limit | requisições permitidas por minuto para a chave |
RateLimit-Remaining | requisições restantes no minuto atual |
RateLimit-Reset | segundos até o limite por minuto renovar |
X-Quota-Limit | cota mensal da organização |
X-Quota-Remaining | requisições restantes no mês |
X-Quota-Reset | quando a cota renova (ISO 8601) |
Erro 429
code | Quando |
|---|---|
rate_limited | limite por minuto da chave, da organização ou do IP |
quota_exceeded | cota mensal esgotada |
A resposta traz o cabeçalho Retry-After com os segundos de espera. Respeite esse valor antes de tentar de novo.
HTTP/1.1 429 Too Many Requests
Retry-After: 18
Content-Type: application/json; charset=utf-8
{
"error": {
"code": "rate_limited",
"internal_code": 106,
"message": "Rate limit of 60 requests per minute for this API key exceeded. Try again in 18s.",
"request_id": "req_01JC…"
}
}
Boas práticas
- Respeite o
Retry-Aftere, para outras falhas temporárias (5xx, rede), tente de novo com intervalos crescentes (por exemplo 1 s, 2 s, 4 s, 8 s), com um limite de tentativas. - Busque só o que mudou com
updated_sincee/v1/deletions, em vez de baixar tudo de novo a cada vez. Veja Paginação e sincronização. - Use
limit=100nas listas para gastar menos requisições. - Use
include=batchesemGET /v1/products/{id}para trazer o produto e os lotes em uma requisição só. - Use
If-None-Matchao consultar um item que você já tem: se nada mudou, a resposta é um304sem corpo. - Espalhe tarefas agendadas pelo minuto, em vez de disparar tudo no segundo zero.