Source: https://maps.vietmap.vn/docs/vi/map-api/errors/ # Mã lỗi và cách xử lý Map API của VIETMAP báo lỗi ở hai chỗ: mã trạng thái HTTP, và với nhóm API chỉ đường thì thêm trường `code` trong JSON. Cần kiểm tra cả hai, vì một request chỉ đường có thể trả HTTP `200` kèm `code: "ZERO_RESULTS"`. ## Mã HTTP | Mã | Ý nghĩa | Cách xử lý | | --- | --- | --- | | `200` | Thành công. Phần lớn API trả JSON, Static Map trả ảnh PNG. | Với Route v4, TSP v4, Matrix v4: kiểm tra tiếp trường `code` (bên dưới). | | `400` | Thiếu tham số hoặc tham số sai định dạng. | Sửa request, đối chiếu với ví dụ trên trang của API đó. | | `401` | API key thiếu, sai hoặc không tồn tại. Thân phản hồi rỗng. | Kiểm tra giá trị `apikey`, xem đã chép đủ services key chưa. | | `413` | File gửi lên quá lớn: `markerFile` của Static Map vượt 10 MB. | Gửi ảnh marker nhỏ hơn hoặc dùng `markerUrl`. | | `423` | Hết hạn mức, API chưa được bật cho key, hoặc dùng tilemap key để gọi Map API. Thân phản hồi là văn bản, ví dụ `Your request is limited`. | Xem [mục 423](#423) ngay dưới. | | `429` | Gửi quá nhiều request trong thời gian ngắn. | Giảm tốc độ gọi, chờ rồi gọi lại, tăng dần thời gian chờ giữa các lần thử. | | `500` | Lỗi phía server. | Gọi lại sau. Lỗi lặp lại thì gửi request đó cho bộ phận hỗ trợ. | `401` trả thân rỗng và `423` trả văn bản, không phải JSON. Vì vậy hãy đọc mã HTTP trước rồi mới parse JSON. ### 423 `423` gồm ba trường hợp: 1. **Hết hạn mức.** Tài khoản Trial dừng từng API khi đủ 500 request trong ngày (riêng Autocomplete không giới hạn theo ngày), và mở lại vào ngày hôm sau. Tài khoản Standard dừng khi dùng hết tổng hạn mức. Tài khoản Enterprise bị chặn trong ngày khi hạn mức ngày lên 100%. Xem mức đã dùng ở [Theo dõi mức dùng API Key](https://maps.vietmap.vn/docs/vi/map-api/console/monitor-api-key-usage/), nạp thêm ở [Thanh toán](https://maps.vietmap.vn/docs/vi/map-api/console/payment/). 2. **API chưa được bật cho key.** Trên tài khoản Trial, Tile, Traffic và Driving Alert mặc định tắt. Kiểm tra API đã bật cho key ở [Quản lý API Key](https://maps.vietmap.vn/docs/vi/map-api/console/manage-api-key/), hoặc liên hệ VIETMAP để mở. 3. **Dùng nhầm key.** Tilemap key chỉ để hiển thị bản đồ; gọi Map API bằng tilemap key sẽ nhận `423`. Gọi Map API bằng services key. ## Trường `code` trong phản hồi chỉ đường Route v4, TSP v4 và Matrix v4 trả thêm trường `code`: | `code` | Ý nghĩa | Cách xử lý | | --- | --- | --- | | `OK` | Thành công. | — | | `INVALID_REQUEST` | Tham số không hợp lệ, chi tiết nằm trong `messages`. | Sửa các tham số mà `messages` chỉ ra. | | `OVER_DAILY_LIMIT` | Key đã vượt giới hạn trong ngày. | Chờ sang ngày mới, hoặc nâng hạn mức. | | `MAX_POINTS_EXCEED` | Số điểm vượt mức cho phép của gói. | Gửi ít điểm hơn, hoặc chia thành nhiều request. | | `ZERO_RESULTS` | Không có đường nối các điểm với loại xe đã chọn. | Kiểm tra thứ tự toạ độ (vĩ độ trước). Với `vehicle=truck` hoặc `container`, gọi lại bằng `car` để biết có điểm nào nằm trên đường cấm xe tải không. | | `ERROR_UNKNOWN` | Lỗi không xác định, chi tiết trong `messages`. | Gọi lại. Lỗi lặp lại thì liên hệ hỗ trợ. | API khác dùng quy ước riêng: [VRP](https://maps.vietmap.vn/docs/vi/map-api/vrp/) trả `code: 0` khi giải xong; [Geofencing](https://maps.vietmap.vn/docs/vi/map-api/geofencing/) trả `code` và `message` là `null` khi thành công. ## Xử lý lỗi trong code Một hàm bọc dùng chung cho mọi lần gọi Map API: gọi lại khi gặp `429`, báo rõ `401` và `423`, kiểm tra `code` của nhóm chỉ đường. === "JavaScript" ```js // Node.js 18+. Gọi từ server để không lộ API key. async function callVietmap(url, init, retries = 3) { for (let attempt = 0; ; attempt++) { const res = await fetch(url, init); if (res.status === 429 && attempt < retries) { await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt)); // 1 s, 2 s, 4 s continue; } if (res.status === 401) throw new Error("VIETMAP 401: API key sai hoặc thiếu"); if (res.status === 423) throw new Error(`VIETMAP 423: ${await res.text()}`); if (!res.ok) throw new Error(`VIETMAP HTTP ${res.status}`); // Static Map trả ảnh: dùng res.arrayBuffer() thay cho res.json() const data = await res.json(); // Nhóm chỉ đường trả "OK" khi thành công; VRP trả 0, Geofencing trả null if (typeof data.code === "string" && data.code !== "OK") { throw new Error(`VIETMAP ${data.code}: ${data.messages ?? ""}`); } return data; } } ``` === "Python" ```python import time import requests def call_vietmap(method, url, retries=3, **kwargs): """Hàm bọc dùng chung cho mọi lần gọi Map API. Trả về JSON đã parse.""" for attempt in range(retries + 1): resp = requests.request(method, url, timeout=30, **kwargs) if resp.status_code == 429 and attempt < retries: time.sleep(2 ** attempt) # 1 s, 2 s, 4 s continue if resp.status_code == 401: raise RuntimeError("VIETMAP 401: API key sai hoặc thiếu") if resp.status_code == 423: raise RuntimeError(f"VIETMAP 423: {resp.text}") resp.raise_for_status() # Static Map trả ảnh: dùng resp.content thay cho resp.json() data = resp.json() # Nhóm chỉ đường trả "OK" khi thành công; VRP trả 0, Geofencing trả None if isinstance(data, dict) and isinstance(data.get("code"), str) and data["code"] != "OK": raise RuntimeError(f"VIETMAP {data['code']}: {data.get('messages', '')}") return data ``` ## Trang liên quan - [Bắt đầu nhanh](https://maps.vietmap.vn/docs/vi/map-api/quickstart/) — lấy key, gọi API đầu tiên, hiện bản đồ. - [Giới hạn sử dụng](https://maps.vietmap.vn/docs/vi/map-api/console/usage-limitation/) — hạn mức từng API theo loại tài khoản. - [Cách tính tiền](https://maps.vietmap.vn/docs/vi/map-api/console/request-to-transaction/) — một request tốn bao nhiêu transaction. - [Quản lý API Key](https://maps.vietmap.vn/docs/vi/map-api/console/manage-api-key/) — bật tắt API, giới hạn domain và IP cho key.