Skip to main content
Para manter a API estável para todos os clientes, a Salvy limita quantas requisições cada empresa pode fazer por minuto. A sua integração consegue acompanhar esse limite pelos cabeçalhos de cada resposta e se ajustar antes de ser bloqueada.

Qual é o limite

  • O limite é por empresa, não por chave de API: todas as chaves da mesma empresa dividem a mesma janela. Criar mais chaves não aumenta o limite.
  • Chaves de organização contam na janela da organização, separada da janela de cada empresa.
  • A janela é fixa de um minuto: ela começa na primeira requisição e zera quando o minuto termina.
Se a sua integração precisa de mais do que isso, fale com o seu contato na Salvy. O limite pode ser ajustado por empresa.

Como acompanhar o limite

As respostas autenticadas trazem dois cabeçalhos: Quando RateLimit-Remaining chegar perto de zero, espace as próximas chamadas em vez de esperar pelo bloqueio. Os cabeçalhos não aparecem em respostas 401 e 403, porque a autenticação é avaliada antes. Trate a ausência de RateLimit-Remaining como “sem informação”, não como limite esgotado.

Quando o limite é atingido

A requisição que passa do limite recebe 429 Too Many Requests com o código too-many-attempts. O cabeçalho Retry-After diz, em segundos, quanto falta para a janela zerar:
Nada é executado numa requisição recusada. É seguro repeti-la depois do tempo indicado, inclusive quando for uma criação ou alteração.

Outro 429: a proteção de borda

Além do limite por empresa, a Salvy tem uma proteção de borda contra picos vindos de um mesmo IP. Ela responde 429 com o código too-many-requests e sem Retry-After. Se receber esse código, aguarde alguns segundos e tente de novo com espera crescente.

Como tratar o 429

Não repita a requisição imediatamente em laço. Enquanto a janela não zerar, toda nova tentativa volta com 429.

Boas práticas

  • Sincronizações em lote: distribua as chamadas ao longo do tempo em vez de disparar tudo de uma vez.
  • Várias integrações na mesma empresa: lembre que elas dividem o mesmo limite. Um job pesado pode esgotar a janela de outra integração.
  • Agentes de IA e scripts: limite a concorrência. Um laço sem pausa atinge 300 requisições em poucos segundos.
  • Teste no sandbox: chaves salvy_test_ seguem o mesmo limite. Veja Ambientes.

Corpo da resposta 429

O corpo segue o formato de erro da v3. O tempo de espera também vem no corpo, para clientes que não leem cabeçalhos: