Loading & errors

Handle initialization, tile failures, key permissions and quota errors.

3 min readVue 3 / Nuxt 4Live example included

On this page

Status Key, permission and quota errors

Interactive exampleMapLibre

Simulate a response

This simulation sends no network request and consumes no quota.

Response code

Vue 3 · TypeScript

<script setup lang="ts">
import { ref } from 'vue'
import { NeshanMapLibre, MAPLIBRE_STYLES, type Coordinates } from 'vue-neshan-maps'
import 'vue-neshan-maps/style.css'

const webKey = import.meta.env.VITE_NESHAN_WEB_KEY
const center = ref<Coordinates>([35.72, 51.36])
const zoom = ref(12.2)
function onResourceError(failure: import('vue-neshan-maps').MapResourceFailure) {
  console.info(failure.kind, failure.retryable)
}
</script>

<template>
  <NeshanMapLibre
    v-model="center" v-model:zoom="zoom"
    :api-key="webKey"
    :styles="{ height: '420px' }"
    :center-marker="false"
    :map-style="MAPLIBRE_STYLES.light"
    :traffic="false" :poi="false"
    @resource-error="onResourceError"
  />
</template>

Set VITE_NESHAN_WEB_KEY in your ignored .env.local. This code reflects the controls above; your actual key is never included.

Status#

The complete example uses three different slots: loading for initialization, error for initialization failure with a retry action, and tile-error for partial resource failure. A partial failure can coexist with a usable map.

Track tiles-loading, tiles-loaded and tile-error separately from ready. Their TileState payload contains status, loaded and failed. MapLibre counts source readiness notifications, while Leaflet counts raster tile results; these counters are not interchangeable. For MapLibre, reinitialization or style/live-layer changes reset failure counters.

Use ariaLabel to describe the map's purpose. Give application buttons readable labels, keyboard focus styles and textual coordinate/status feedback. Slots let you adapt messages without replacing the renderer.

Key, permission and quota errors#

Subscribe to resource-error; initialization still emits error, and partial failures retain warning / tile-error. The structured payload is MapResourceFailure: kind, safe message, optional numeric status, code, retryAfter (seconds), and retryable.

Neshan code / HTTP status	`kind`	Action
480 / 401	`invalid-key`	Check the web key
483	`key-type`	Use a key matching this web service
484	`domain`	Check allowed origins/domains in the Neshan panel
485	`service`	Enable the required map/traffic/POI permission
481	`quota`	Check account usage and quota; automatic retry cannot fix exhausted quota
482 / 429	`rate-limit`	Back off; honor `retryAfter` when provided
403 without a provider code	`forbidden`	Access was denied; the response does not identify the exact cause
470 / 400	`request`	Check tile/request parameters
5xx	`server`	Retry later with bounded backoff
Connection failure	`network`	Check connectivity / CORS; browser failures cannot reliably distinguish them
Vector decode failure	`decode`	Check data/codec compatibility
Other renderer error	`unknown`	Inspect trusted native diagnostics in development

Provider response codes take precedence over generic HTTP status. Worker serialization preserves numeric details and Retry-After. Raw response bodies and request URLs/keys are not emitted. retryable is advice; the wrapper does not automatically loop or deliberately consume quota. retry() explicitly recreates the map. Tile counters reset on retry or style/live-layer changes.

Found something unclear?View the source Report an issue

Loading & errors

Run on a real Neshan map

Status#

Key, permission and quota errors#