Pular para o conteúdo

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çalhoSignificado
RateLimit-LimitPedidos permitidos por minuto nesse limite.
RateLimit-PolicyA política desse limite, pedidos;w=segundos (por exemplo 120;w=60).
RateLimit-RemainingQuantos ainda cabem agora.
RateLimit-ResetSegundos 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.

Node.js
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 updatedSince e limit=100 em vez de baixar tudo de novo (paginação).
  • Para reagir a mudanças, receba webhooks em vez de perguntar a cada minuto.
  • Acompanhe RateLimit-Remaining e 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.
PróximoWebhooks