Bỏ qua

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 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, nạp thêm ở Thanh toán.
  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, 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 trả code: 0 khi giải xong; 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.

// 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;
  }
}

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

Hotline
Tổng đài hỗ trợ
089.616.4567 Messenger Chat Facebook zalo Chat Zalo