Lỗi & giới hạn tốc độ
Mã lỗi
Lỗi luôn có dạng { requestId, error: { code, message } }. Xử lý theo code, không theo message — nội dung message dành cho người đọc và có thể được chỉnh lại.
| HTTP | error.code | Khi nào | Thử lại? |
|---|---|---|---|
| 400 | INVALID_DATE | Thiếu hoặc sai định dạng from, to. | Không — sửa yêu cầu |
| 400 | INVALID_RANGE | to trước from, hoặc khoảng quá 31 ngày. | Không — sửa yêu cầu |
| 400 | INVALID_STATUS | status không hợp lệ. | Không — sửa yêu cầu |
| 400 | INVALID_PAGE | page hoặc pageSize sai. | Không — sửa yêu cầu |
| 400 | INVALID_UPDATED_SINCE | updatedSince không phải thời điểm ISO 8601 có múi giờ, hoặc xuất hiện nhiều lần. | Không — sửa yêu cầu |
| 400 | INVALID_CURSOR | cursor không hợp lệ, hoặc do đường dẫn khác cấp. | Không — dùng đúng nextCursor |
| 400 | INVALID_LIMIT | limit không phải số nguyên từ 1 đến 500. | Không — sửa yêu cầu |
| 400 | UNKNOWN_PARAMETER | Tham số không được hỗ trợ ở đường dẫn này (chỉ với đường dẫn mới; /encounters vẫn bỏ qua tham số lạ). | Không — sửa yêu cầu |
| 401 | UNAUTHORIZED | Thiếu, sai hoặc key đã bị thu hồi; hoặc phòng khám đang bị tạm ngưng. | Không — kiểm tra lại key |
| 403 | INSUFFICIENT_SCOPE | Key hợp lệ nhưng không có quyền đọc đường dẫn này. | Không — xin quyền từ quản trị viên |
| 404 | NOT_FOUND | Không có bản ghi với id này trong phòng khám của key. | Không |
| 405 | METHOD_NOT_ALLOWED | Chỉ hỗ trợ GET. | Không |
| 429 | RATE_LIMITED | Vượt giới hạn tốc độ hoặc IP đang bị khoá tạm. | Có — sau Retry-After |
| 5xx | — | Lỗi phía máy chủ. | Có — chờ tăng dần |
{
"requestId": "req_7c1f3a",
"error": {
"code": "INVALID_RANGE",
"message": "`to` phải sau `from` và khoảng tối đa 31 ngày."
}
}Giới hạn tốc độ (rate limit)
60yêu cầu mỗi phút, tính theo từng key
5lần gửi sai key trong 10 phút, từ cùng một IP
15′IP bị khoá tạm thời, dù sau đó gửi đúng key
Cả hai giới hạn trả về 429 RATE_LIMITED kèm header Retry-After (số giây). Hãy chờ đúng khoảng đó rồi thử lại, đừng gọi lặp liên tục.
Đừng để hệ thống tự thử lại khi gửi sai key. Một vòng lặp gửi sai key sẽ khoá IP của bạn 15 phút. Khi gặp
401, dừng lại và báo cho người phụ trách kiểm tra key.
async function callWithRetry(url, options, attempts = 4) {
for (let i = 0; i < attempts; i += 1) {
const res = await fetch(url, options);
if (res.status === 429) {
const seconds = Number(res.headers.get('Retry-After')) || 30;
await new Promise((r) => setTimeout(r, seconds * 1000));
continue;
}
if (res.status >= 500) {
await new Promise((r) => setTimeout(r, 2 ** i * 1000));
continue;
}
return res; // 2xx, 4xx: không thử lại
}
throw new Error('Hết số lần thử');
}Hỗ trợ
Khi cần hỗ trợ, hãy gửi kèm requestId của yêu cầu lỗi (có trong thân phản hồi và header X-Request-Id), thời điểm gọi và tham số bạn đã dùng. Đừng gửi kèm API key — nếu lỡ gửi, hãy thu hồi key đó ngay.