Rate limits e códigos de erro

O limite de pedidos (rate limit) protege a API contra sobrecarga e abuso. Se enviar demasiados pedidos em pouco tempo, o servidor responde com HTTP 429 Too Many Requests com o cabeçalho Retry-After, que indica quantos segundos esperar.

Limites atuais

• O limite é de 60 pedidos por minuto por cada token. Aplica-se da mesma forma a todos os planos (Trial, Standard, Pro e Business).
• Os agentes LAN têm um limite separado de 120 pedidos por minuto por cada agente.
• O limite é contado por cada token separadamente (não por utilizador inteiro). Se precisar de um teto total mais alto, crie mais tokens para diferentes usos (por exemplo, um para CI/CD e outro para o dashboard).

Códigos de erro

• 401 Unauthorized - token em falta ou inválido.
• 403 Forbidden - a ação não está disponível no seu plano (por exemplo, criar um monitor após a expiração do plano ou acima do limite do seu plano).
• 404 Not Found - o recurso indicado (monitor, incidente) não existe ou não tem acesso.
• 429 Too Many Requests - limite de pedidos excedido. Aguarde o número de segundos indicado no cabeçalho Retry-After.
• 5xx - erro do lado do servidor. Tente novamente com um atraso progressivamente maior (exponential backoff - por exemplo, 1, 2, 4, 8 segundos).

Recomendações práticas

• Guarde as respostas dos endpoints de leitura numa cache. Os dados de disponibilidade não mudam a cada segundo, não precisa de os puxar com tanta frequência.
• Onde for possível, em vez de polling repetido use webhooks - o servidor chama-o por si quando ocorre um evento.
• Em operações em lote, adicione um pequeno atraso entre pedidos para não se aproximar do limite.