Source: https://maps.vietmap.vn/docs/map-api/errors/

# 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](#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](https://maps.vietmap.vn/docs/map-api/console/monitor-api-key-usage/) and top up in [Payment & Billing](https://maps.vietmap.vn/docs/map-api/console/payment/).
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](https://maps.vietmap.vn/docs/map-api/console/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](https://maps.vietmap.vn/docs/map-api/vrp/) returns `code: 0` when solved, and [Geofencing](https://maps.vietmap.vn/docs/map-api/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.

=== "JavaScript"

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

=== "Python"

    ```python
    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
    ```

## Related pages

- [Quickstart](https://maps.vietmap.vn/docs/map-api/quickstart/) — get your keys, make the first call, show a map.
- [Usage limits](https://maps.vietmap.vn/docs/map-api/console/usage-limitation/) — per-API limits by account type.
- [How pricing works](https://maps.vietmap.vn/docs/map-api/console/request-to-transaction/) — how many transactions a request costs.
- [Manage API key](https://maps.vietmap.vn/docs/map-api/console/manage-api-key/) — enable APIs and restrict a key by domain or IP.