API v1 · Guia
Limites de requisição
Quantos pedidos por minuto cada token e cada empresa podem fazer, e como tratar o 429.
Cada token pode fazer até 120 pedidos por minuto e a empresa inteira, somando todos os tokens, até 600 por minuto. A janela é deslizante: vale a soma dos últimos 60 segundos, sem virada de minuto. Os limites são iguais em todos os planos.
Mesmo com a empresa no teto, cada token tem 60 pedidos por minuto garantidos: um robô
que esgotou os 600 da empresa (por exemplo, com vários tokens) não derruba a integração dos
outros. Passados esses 60, o token recebe 429 da empresa até a janela abrir. Enquanto a
empresa está no teto, os cabeçalhos mostram a cota garantida do token (RateLimit-Limit: 60).
O pedido é contado antes de qualquer outra checagem, então toda resposta informa a
situação do limite mais apertado no momento (o do token ou o da empresa), inclusive as de
erro (401, 402, 403, 404, 429):
| Cabeçalho | Significado |
|---|---|
RateLimit-Limit | Pedidos permitidos por minuto nesse limite. |
RateLimit-Policy | A política desse limite, pedidos;w=segundos (por exemplo 120;w=60). |
RateLimit-Remaining | Quantos ainda cabem agora. |
RateLimit-Reset | Segundos até abrir a próxima vaga. |
Os mesmos valores saem também em X-RateLimit-Limit, X-RateLimit-Remaining e
X-RateLimit-Reset. Ao passar do limite a resposta é 429 com code: rate_limited e o
cabeçalho Retry-After: espere esse número de segundos antes de repetir o pedido. No
envio de mensagem, o 429 do limite por número traz nesses cabeçalhos o limite do número.
Falhas de autenticação (sem token, Authorization malformado, token inexistente,
revogado ou expirado) contam também por endereço IP: passando de 60 por minuto, o IP
recebe 429 em pedidos com token que ainda não autenticou, até a janela abrir. Nessas
respostas os cabeçalhos mostram esse limite. Um token que já autenticou segue normalmente.
O corpo do pedido vai até 1 MB e precisa chegar inteiro em até 30 segundos. Acima
de 1 MB a resposta é 413 payload_too_large; corpo que não chega inteiro a tempo (conexão
lenta ou que caiu no meio do envio) responde 408 request_timeout. Nos dois casos nada foi
executado: o 408 pode ser repetido com a mesma Idempotency-Key; o 413, só com um
corpo menor. Se o servidor estiver recebendo dados demais ao mesmo tempo, a resposta é
503 server_busy com Retry-After, também sem executar nada.
Como tratar o 429
Espere o Retry-After e repita. Antes disso, o pedido só recebe outro 429.
async function pedir(url, opcoes, tentativas = 5) {
for (let tentativa = 1; ; tentativa++) {
const resposta = await fetch(url, opcoes);
if (resposta.status !== 429 || tentativa === tentativas) return resposta;
const segundos = Number(resposta.headers.get("Retry-After")) || 1;
await new Promise((pronto) => setTimeout(pronto, segundos * 1000));
}
}Gastar menos pedidos
- Sincronize com
updatedSinceelimit=100em vez de baixar tudo de novo (paginação). - Para reagir a mudanças, receba webhooks em vez de perguntar a cada minuto.
- Acompanhe
RateLimit-Remaininge desacelere antes de chegar a zero. - Todos os tokens da empresa somam no limite da empresa, mas cada token tem 60 pedidos por minuto garantidos mesmo com a empresa no teto: um robô mal comportado não derruba a integração dos outros.