Rate Limiting

Cartrack Fleet API áp dụng rate limiting cho mọi API request đi vào để bảo vệ tài nguyên mạng, duy trì hiệu năng hệ thống và đảm bảo trải nghiệm nhất quán cho tất cả người dùng.

Default Rate Limit

API có default rate limit là 1,000 requests mỗi phút. Giới hạn này áp dụng cho hầu hết endpoint API nếu không có ghi chú khác. Bất kỳ request nào vượt quá giới hạn này sẽ nhận phản hồi HTTP 429 Too Many Requests.

API Endpoint Specific Rate Limit

Một số endpoint API có giới hạn chặt hơn để đảm bảo công bằng và ngăn chặn lạm dụng. Bên dưới là giới hạn cụ thể cho các endpoint này:

Endpoint	Rate Limit	Description
POST /fuel/consumed	10 requests mỗi phút	Truy xuất ước tính fuel used cho nhiều phương tiện.
POST /fuel/level	10 requests mỗi phút	Truy xuất dữ liệu cảm biến fuel consumed cho nhiều phương tiện.
POST /vehicles/ev-consumption	10 requests mỗi phút	Truy xuất mức tiêu thụ pin của nhiều xe điện.
POST /vehicles/range	10 requests mỗi phút	Truy xuất các event EV range được báo cáo cho nhiều xe điện.
POST /vehicles/soc	10 requests mỗi phút	Truy xuất event state of charge (SoC) cho nhiều xe điện.
GET /vehicles/vext	10 requests mỗi phút	Truy xuất dữ liệu VEXT của phương tiện bất kể trạng thái ignition.

Với endpoint có giới hạn riêng, vượt quá giới hạn cũng sẽ trả về HTTP 429 Too Many Requests.

Hành vi retry

Nếu nhận phản hồi HTTP 429 Too Many Requests, quý khách phải tuân thủ các header trong phản hồi. Các header này cho biết khi nào có thể retry:

• X-RateLimit-Retry-At: Timestamp cho lần retry sớm nhất tiếp theo.
• X-RateLimit-Retry-After-Seconds: Số giây cần chờ trước lần retry sớm nhất tiếp theo.

Ví dụ phản hồi

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."
    }
}

Cách xử lý 429 Too Many Requests

• Wait and Retry: Tuân thủ header X-RateLimit-Retry-At và X-RateLimit-Retry-After-Seconds để chờ đúng thời gian được khuyến nghị trước khi retry.
• Exponential Backoff: Triển khai exponential backoff có jitter để tránh vi phạm rate limit lặp lại.

Lưu ý: Vi phạm rate limit lặp lại có thể dẫn đến giới hạn truy cập tạm thời hoặc vĩnh viễn.

Tăng giới hạn

Nếu ứng dụng của quý khách cần rate limit cao hơn, quý khách có thể gửi yêu cầu tăng giới hạn. Yêu cầu sẽ được đánh giá theo từng trường hợp để đảm bảo phù hợp với hạ tầng của chúng tôi. Giới hạn được phê duyệt sẽ được tùy chỉnh và thông báo tương ứng.