Referência Técnica
Rate limits
Limites de requisições, cabeçalhos HTTP e uso responsável da API Nuvende v2
A Nuvende pode aplicar limites de taxa (throttling) por rota, credencial ou IP para proteger a plataforma e garantir uso justo. Quando um limite é atingido, a API responde normalmente com HTTP 429 Too Many Requests — ver também Códigos de erro.
Cabeçalhos úteis (quando expostos)
Em muitas APIs REST, os limites são comunicados em cabeçalhos de resposta. Valores exatos dependem do produto e do ambiente; monitore na integração:
| Cabeçalho (exemplo) | Significado |
|---|---|
X-RateLimit-Limit | Máximo de requisições na janela atual |
X-RateLimit-Remaining | Requisições restantes antes do bloqueio |
X-RateLimit-Reset | Tempo até reinício da janela (em segundos, conforme implementação) |
Retry-After | Segundos a aguardar antes de repetir (comum em 429) |
Se o seu cliente receber 429, respeite Retry-After quando existir; caso contrário, use backoff exponencial (ex.: 1s, 2s, 4s) com limite máximo de tentativas.
Exemplo orientativo (Cobranças / webhooks)
Limites indicativos podem aparecer na documentação de Cobranças. Trate-os como ordem de grandeza — a quota da sua credencial pode diferir.
Boas práticas:
- Evitar polling agressivo; prefira Webhooks para recebimento Pix.
- Cachear tokens até perto de
expires_in. - Nas consultas de extrato, use intervalos e paginação (
offset/limit) em vez de muitas chamadas paralelas.
Onde confirmar valores
- Testar no sandbox com a sua
client_ide medir respostas 429 e cabeçalhos. - Em dúvida sobre limites comerciais ou aumento de quota, alinhar com suporte / time técnico da Nuvende.