Skip to content

Error codes

The VIETMAP Map APIs report problems in two places: the HTTP status and, for the routing APIs, a code field in the JSON body. Check both, because a routing request can return HTTP 200 with code: "ZERO_RESULTS".

HTTP status

Status Meaning What to do
200 Success. Most APIs return JSON; Static Map returns a PNG image. For Route v4, TSP v4 and Matrix v4, also check code (below).
400 A parameter is missing or malformed. Fix the request; compare it with the example on the API's page.
401 The API key is missing, wrong or unknown. The body is empty. Check the apikey value and that you copied the whole services key.
413 The upload is too large: Static Map markerFile over 10 MB. Send a smaller marker image, or use markerUrl.
423 Quota used up, the API is not enabled for this key, or a tilemap key was used for a Map API. The body is plain text, for example Your request is limited. See 423 below.
429 Too many requests in a short time. Slow down, wait and retry, and lengthen the wait on each retry.
500 Server error. Retry later. If it keeps happening, send the request to support.

401 has an empty body and 423 a plain-text body, not JSON, so read the status before you parse JSON.

423

423 covers three situations:

  1. Quota used up. On a Trial account each API stops at 500 requests a day (Autocomplete has no daily cap) and resumes the next day. A Standard account stops when the total quota is used. An Enterprise account is blocked for the rest of the day when the daily quota reaches 100%. Check usage in Monitor API key usage and top up in Payment & Billing.
  2. The API is not enabled for the key. On Trial accounts, Tile, Traffic and Driving Alert are off by default. Check that the API is on for the key in Manage API key, or contact VIETMAP to enable it.
  3. Wrong key type. The tilemap key only renders the map; a Map API called with it returns 423. Call Map APIs with the services key.

code in routing responses

Route v4, TSP v4 and Matrix v4 also return a code field:

code Meaning What to do
OK Success. —
INVALID_REQUEST Parameters failed validation; details are in messages. Fix the parameters named in messages.
OVER_DAILY_LIMIT The key went over its daily limit. Wait for the next day, or raise the limit.
MAX_POINTS_EXCEED More points than your plan allows. Send fewer points, or split the request.
ZERO_RESULTS No road connects the points for the chosen vehicle. Check the coordinate order (latitude first). With vehicle=truck or container, retry with car to find a point on a road closed to trucks.
ERROR_UNKNOWN Unexpected error; details are in messages. Retry. Contact support if it keeps happening.

Other APIs use their own convention: VRP returns code: 0 when solved, and Geofencing returns null in code and message on success.

Handling errors in code

One wrapper for every Map API call: it retries on 429, reports 401 and 423 clearly and checks code on routing responses.

// Node.js 18+. Call from your server so the API key stays private.
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: wrong or missing API key");
    if (res.status === 423) throw new Error(`VIETMAP 423: ${await res.text()}`);
    if (!res.ok) throw new Error(`VIETMAP HTTP ${res.status}`);
    // Static Map returns an image: use res.arrayBuffer() instead of res.json()
    const data = await res.json();
    // Routing APIs return "OK" on success; VRP returns 0 and Geofencing 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):
    """One wrapper for every Map API call. Returns the parsed JSON."""
    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: wrong or missing API key")
        if resp.status_code == 423:
            raise RuntimeError(f"VIETMAP 423: {resp.text}")
        resp.raise_for_status()
        # Static Map returns an image: use resp.content instead of resp.json()
        data = resp.json()
        # Routing APIs return "OK" on success; VRP returns 0 and Geofencing 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
Hotline
Tổng đài hỗ trợ
089.616.4567 Messenger Chat Facebook zalo Chat Zalo