Rate limit

Mỗi request làm tăng hai bộ đếm trong Redis: một cửa sổ theo phút và một cửa sổ theo ngày. Cả hai đều phải vượt qua thì request mới được tiếp tục.

Hạn mức theo từng gói

Mọi response được bảo vệ đều mang theo:

X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 42
X-RateLimit-Limit-Day: 1000
X-RateLimit-Remaining-Day: 870

Hãy dùng chúng để chủ động giảm tải thay vì chờ đến khi gặp 429.

Bạn sẽ nhận được HTTP 429 với một trong các nội dung sau:

{
  "error": "rate limit exceeded (per minute)",
  "code": "RATE_LIMIT_MINUTE",
  "retry_after": 27,
  "request_id": "8f0e1c54-..."
}

{
  "error": "rate limit exceeded (daily quota)",
  "code": "RATE_LIMIT_DAY",
  "retry_after": 41203,
  "request_id": "8f0e1c54-..."
}

retry_after được tính bằng giây. Hãy chờ đúng khoảng thời gian đó rồi thử lại — hoặc hiển thị giới hạn này cho người dùng của bạn.

/v1/demo/suggest được rate-limit theo IP của client, không phải theo key — 30 requests/phút. Vẫn áp dụng các header tương tự.

Cache các kết quả geocoding thành công ở phía client (place ID là ổn định).
Dùng ?sessionToken=... trên /v1/suggest để cả một phiên autocomplete được tính phí như một request thay vì tính theo từng lần gõ phím.
Với khối lượng công việc đột biến, hãy nâng cấp lên PRO trước khi cửa sổ theo ngày được reset.