A API da Veploy limita a quantidade de requisições por minuto. O limite é
contado por API Key, e não por endereço de origem: cada integração tem seu
próprio saldo, então uma chave que atinge o limite não afeta as demais.Limites atuais#
| Tipo de rota | Requisições por minuto |
|---|
| Listagens (as coleções de qualquer recurso) | 30 |
| Consulta individual (um recurso pelo identificador) | 60 |
| Demais rotas | 30 |
O teto vale por tipo de rota, não por recurso: recurso novo entra numa dessas
faixas. O valor exato de cada rota vem no header x-ratelimit-limit da própria
resposta.Os limites são conservadores por escolha. Se a sua integração precisar de mais,
entre em contato: nós ampliamos o limite da chave em vez de deixar você
contornar o controle com várias credenciais.Acompanhar o saldo#
Toda resposta traz o estado atual do limite nos headers:| Header | Significado |
|---|
x-ratelimit-limit | Teto de requisições da rota, por minuto. |
x-ratelimit-remaining | Quantas ainda podem ser feitas na janela atual. |
x-ratelimit-reset | Segundos até a janela reiniciar. |
Ler esses headers é mais confiável do que contar requisições no seu código,
porque o teto pode mudar sem alteração de versão.Quando o limite é atingido#
A resposta é 429 Too Many Requests, no mesmo envelope de erro dos demais
status, com o header retry-after em segundos:{
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Retry in 1 minute."
}
}
Aguarde o tempo indicado em retry-after antes de repetir a requisição. Repetir
imediatamente apenas consome o saldo da próxima janela.Boas práticas#
Use per_page=100 nas listagens. Menos requisições trazendo mais itens
por página é a forma mais eficiente de percorrer um catálogo grande.
Faça requisições em sequência, não em paralelo. Disparar várias ao mesmo
tempo esgota o saldo em poucos segundos e não deixa margem para novas
tentativas.
Sincronize apenas o que mudou. Depois da primeira carga, use
updated_after para buscar somente os registros alterados desde a última
execução. Uma verificação incremental costuma custar uma única requisição,
contra dezenas de uma varredura completa.
Guarde o resultado da carga inicial. Percorrer o catálogo inteiro é uma
operação de primeira execução, não de rotina.
Trate 429 como situação esperada. Uma integração bem construída
aguarda e repete, em vez de falhar.
Modificado em 2026-09-08 21:45:20