Pular para o conteúdo principal
A API aplica três limites, em camadas. Quase toda integração só encontra o primeiro.

Limite da conta

Pense num balde com 20 fichas. Cada requisição gasta uma ficha, e o balde ganha 10 fichas por segundo, até voltar a 20. Na prática:
  • Em ritmo constante, a conta faz até 10 requisições por segundo.
  • Uma rajada de até 20 requisições de uma vez passa, se o balde estiver cheio.
  • O limite é da conta: soma todas as chaves e todos os recursos. Criar mais chaves não aumenta o limite; duas integrações da mesma conta dividem o mesmo balde.
Toda resposta autenticada traz o estado do balde: Acima do limite, a resposta é 429 rate_limited. Espere os segundos de Retry-After antes de repetir. Repetir antes só gasta tempo: o balde ainda está vazio.

Falhas de autenticação por IP

Depois de 30 respostas 401 para o mesmo IP em 60 segundos, as requisições seguintes desse IP recebem 429 rate_limited com Retry-After até o fim da janela. Uma integração que repete com a chave errada se bloqueia: corrija a chave em vez de repetir. O bloqueio poupa a chave válida que autenticou com sucesso nas últimas 24 horas: ela segue funcionando mesmo com o IP bloqueado. Isso protege quem divide o IP de saída com outras contas, como no n8n cloud, no Make e no Zapier. Uma chave válida sem sucesso nesse período (por exemplo, recém-criada e ainda não usada) recebe 429 até o fim da janela, como as demais.

Volume por IP

Acima de 15.000 requisições em 5 minutos vindas do mesmo IP, a borda da Zouti responde 429 sem corpo JSON e com Retry-After: 300. Esse limite vale antes da autenticação, para qualquer chave.
O 429 do limite por IP não tem error.code. Trate o 429 pelo status HTTP e pelo header Retry-After, nunca pelo corpo.

Como ficar dentro do limite

  1. Leia RateLimit-Remaining. Quando chegar a 0, espere os segundos de RateLimit-Reset antes da próxima chamada.
  2. No 429, espere Retry-After e repita a mesma requisição.
  3. Prefira poucas chamadas grandes. Use limit=100 ao percorrer listas: são 100 pedidos por requisição em vez de 20.
  4. Não leia tudo de novo a cada rodada. Leia só o que mudou com a sincronização incremental.
  5. Evite muitas requisições em paralelo com a mesma conta: todas gastam o mesmo balde.
O código ao lado percorre todos os pedidos seguindo as regras 1 a 3. Para um cliente que também repete 500 e 503 com espera crescente, veja Erros.