Rate Limiting

A Cartrack Fleet API aplica rate limiting a todos os pedidos de API recebidos para proteger recursos de rede, manter o desempenho do sistema e garantir uma experiência consistente para todos os utilizadores.

Limite padrão

A API tem um limite padrão de 1.000 pedidos por minuto. Este limite aplica-se à maioria dos endpoints, salvo indicação em contrário. Qualquer pedido acima deste limite receberá HTTP 429 Too Many Requests.

Limites específicos por endpoint

Alguns endpoints têm limites mais restritivos para garantir equidade e prevenir abuso. Veja abaixo os limites específicos:

Endpoint	Rate Limit	Descrição
POST /fuel/consumed	10 pedidos por minuto	Obter estimativa de combustível usado para vários veículos.
POST /fuel/level	10 pedidos por minuto	Obter dados do sensor de combustível consumido para vários veículos.
POST /vehicles/ev-consumption	10 pedidos por minuto	Obter consumo de bateria para vários veículos elétricos.
POST /vehicles/range	10 pedidos por minuto	Obter eventos de autonomia (range) para vários veículos elétricos.
POST /vehicles/soc	10 pedidos por minuto	Obter eventos de state of charge (SoC) para vários veículos elétricos.
GET /vehicles/vext	10 pedidos por minuto	Obter dados VEXT dos veículos independentemente do estado da ignição.

Para limites específicos por endpoint, ultrapassar o limite também resulta em HTTP 429 Too Many Requests.

Comportamento de retry

Se receber HTTP 429 Too Many Requests, deve respeitar os cabeçalhos presentes na resposta. Estes cabeçalhos indicam quando pode voltar a tentar:

• X-RateLimit-Retry-At: timestamp da próxima tentativa permitida.
• X-RateLimit-Retry-After-Seconds: número de segundos até à próxima tentativa permitida.

Exemplo de resposta

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Retry-At: 1737592000
X-RateLimit-Retry-After-Seconds: 15

{
    "error": {
        "code": 429,
        "message": "Too many requests. Please wait before retrying."
    }
}

Como tratar 429 Too Many Requests

• Esperar e repetir: Respeite os cabeçalhos X-RateLimit-Retry-At e X-RateLimit-Retry-After-Seconds antes de repetir.
• Exponential backoff: Implemente exponential backoff com jitter para evitar novas violações de limite.

Notas: Violações repetidas de rate limiting podem resultar em restrições de acesso temporárias ou permanentes.

Aumentar o limite

Se a sua aplicação precisar de um limite superior, pode submeter um pedido de aumento. Os pedidos serão avaliados caso a caso para garantir compatibilidade com a nossa infraestrutura. Os limites aprovados serão personalizados e comunicados em conformidade.