Error Codes Reference

All API errors are instances of MapstedError, which extends the standard Error class with a structured MAPSTED-1xxx code.

import { MapstedError } from '@mapsted/maps-js-api';

try {
  await maps.navigateToFloorById(999);
} catch (err) {
  if (err instanceof MapstedError) {
    console.error(err.code);    // e.g. "MAPSTED-1040"
    console.error(err.message); // human-readable interpolated message
  }
}

Each error has a recoverable flag. Recoverable errors indicate a transient condition where retrying (after taking corrective action) may succeed. Non-recoverable errors indicate programming mistakes or permanent configuration problems.

---

Initialisation — 1000–1009

Code	Symbolic name	Recoverable	Message template	Resolution
MAPSTED-1000	ERR_INIT_FAILED	No	Mapsted Maps JavaScript API initialisation failed: {reason}	Check the reason field for the root cause. Common causes: DOM not ready, iframe blocked by CSP.
MAPSTED-1001	ERR_ALREADY_INITIALISED	No	Mapsted Maps JavaScript API is already initialised. Call destroy() before re-initialising.	Call destroy() before calling init() a second time.

---

Configuration — 1010–1019

Code	Symbolic name	Recoverable	Message template	Resolution
MAPSTED-1010	ERR_MISSING_PROPERTY_ID	No	propertyId is required in Mapsted Maps JavaScript API configuration.	Supply propertyId in InitOptions when using npm mode.
MAPSTED-1011	ERR_INVALID_MAPS_DOMAIN	No	mapsDomain '{domain}' is not a valid Mapsted Maps domain.	Provide a valid absolute URL for the maps backend (e.g. https://maps.mapsted.com).
MAPSTED-1012	ERR_MISSING_REQUIRED_PARAM	No	Required parameter '{parameter}' is missing or null.	Supply the named parameter. Check the method signature for required fields.
MAPSTED-1013	ERR_INVALID_PARAM_TYPE	No	Parameter '{parameter}' expected type '{expected}' but received '{actual}'.	Pass the correct type. expected and actual in the message describe the mismatch.

---

Iframe / DOM — 1020–1029

Code	Symbolic name	Recoverable	Message template	Resolution
MAPSTED-1020	ERR_IFRAME_NOT_FOUND	No	Target iframe element not found. Verify the selector: '{selector}'.	Ensure the container element exists in the DOM before calling init().
MAPSTED-1021	ERR_IFRAME_NOT_READY	Yes	iframe has not completed loading. Await the READY event before sending commands.	Wait for the load event or the onload callback before calling command methods.

---

Communication — 1030–1039

Code	Symbolic name	Recoverable	Message template	Resolution
MAPSTED-1030	ERR_COMMAND_TIMEOUT	Yes	Command '{action}' timed out after {ms}ms (requestId: {requestId}).	The iframe did not respond within 10 s. Verify the map is fully loaded. Retry after confirming isReady().
MAPSTED-1031	ERR_POSTMESSAGE_FAILED	No	postMessage delivery failed. iframe may have been destroyed.	Check that destroy() was not called before the command. Re-initialise if needed.

---

Navigation — 1040–1049

Code	Symbolic name	Recoverable	Message template	Resolution
MAPSTED-1040	ERR_INVALID_FLOOR_ID	No	Floor ID '{floorId}' is not valid for property '{propertyId}'.	Use getFloors() to retrieve valid floor IDs for the current property.
MAPSTED-1041	ERR_INVALID_FLOOR_NAME	No	Floor name '{floorName}' not found in property '{propertyId}'.	Verify the floor name against getFloors() results. Names are case-sensitive.
MAPSTED-1042	ERR_INVALID_BUILDING_ID	No	Building ID '{buildingId}' is not valid for property '{propertyId}'.	Confirm the building ID from the Mapsted Hub or CMS.
MAPSTED-1043	ERR_INVALID_VIEWPORT	No	Viewport parameters are invalid: {reason}.	Ensure zoomLevel is 10–24 and mapCenter is [lng, lat] with lng ∈ [−180, 180] and lat ∈ [−90, 90].

---

Quota — 1050

Code	Symbolic name	Recoverable	Message template	Resolution
MAPSTED-1050	ERR_QUOTA_EXCEEDED	Yes	API quota exceeded for tier '{tier}'. Retry after {retryAfter}.	Implement exponential back-off. retryAfter is an ISO 8601 duration string (e.g. PT30S). Upgrade your plan if the limit is reached regularly.

---

POI — 1060–1069

Code	Symbolic name	Recoverable	Message template	Resolution
MAPSTED-1060	ERR_POI_NOT_FOUND	No	POI '{poiId}' not found in property '{propertyId}'.	The entity ID does not exist in the current property. Verify the ID from the Mapsted Hub.
MAPSTED-1061	ERR_INVALID_ENTITY_DATA	No	Entity data is invalid: {reason}.	setEntityData() / setEntityDataById() / setEntityDefaults() require a plain MapEntity object. Arrays and non-objects are rejected.
MAPSTED-1062	ERR_INVALID_COORDS_DATA	No	Coordinates data is invalid: {reason}.	Ensure each element in the CoordsData[] array has valid lat, long, and floor fields.

---

Wayfinding — 1070–1079

Code	Symbolic name	Recoverable	Message template	Resolution
MAPSTED-1070	ERR_ROUTE_NOT_FOUND	No	No route found between POI '{origin}' and POI '{destination}'.	The map graph has no path between these entities. Check that both are on a connected floor plan.
MAPSTED-1071	ERR_INVALID_ROUTING_CONFIG	No	Routing configuration is invalid: {reason}.	Validate the Boost object shape. RoutingBoost requires a non-empty routing string; SelectEntityBoost requires a numeric entity field.
MAPSTED-1072	ERR_INVALID_ACCESSIBILITY_MODE	No	Accessibility mode value must be a boolean, received '{value}'.	Pass true or false to setAccessibilityMode().

---

Search — 1080–1089

Code	Symbolic name	Recoverable	Message template	Resolution
MAPSTED-1080	ERR_INVALID_OVERLAY_MARKERS	No	Overlay markers data is invalid: {reason}.	Pass an array to setMapOverlayMarkers().
MAPSTED-1081	ERR_OVERLAY_NOT_FOUND	No	Map overlay '{overlayId}' not found.	Confirm the overlay ID from the Mapsted CMS. IDs are case-sensitive.
MAPSTED-1082	ERR_INVALID_LANGUAGE_CODE	No	Language code '{code}' is not a valid BCP 47 language tag.	Use a valid BCP 47 tag such as "en", "fr", or "zh-Hans".
MAPSTED-1083	ERR_INVALID_FEATURE_FLAGS	No	Feature flags object is invalid: {reason}.	Pass a plain object to setFeatureFlags(). Arrays are rejected.
MAPSTED-1084	ERR_INVALID_IDLE_TIME	No	Idle time must be a positive integer in milliseconds, received '{value}'.	Pass a positive integer. Floating-point values and zero are rejected.
MAPSTED-1085	ERR_THEME_UNAVAILABLE	Yes	Requested theme is unavailable for this property: {message}.	Call getThemes() to retrieve available theme ids. Theme ids are case-sensitive. Use "light" / "dark" aliases for the built-in Mapsted themes.
MAPSTED-1086	ERR_BUILDING_NOT_FOUND	Yes	Building '{buildingId}' was not found for this property: {message}.	Call getBuildingInfo() with a valid building ID. Confirm the building ID from the Mapsted Hub or CMS for the current property.

---

State — 1090–1099

Code	Symbolic name	Recoverable	Message template	Resolution
MAPSTED-1090	ERR_NOT_READY	Yes	Cannot call '{method}': Mapsted Maps JavaScript API is not in READY state (current: {state}).	Await the load event or check isReady() before calling command methods.
MAPSTED-1091	ERR_SUBSCRIBE_INVALID_HANDLER	No	subscribe() requires a function handler, received '{type}'.	Pass a function reference to subscribe().
MAPSTED-1092	ERR_DESTROY_FAILED	No	destroy() failed: {reason}.	Inspect the reason field. This may indicate a DOM inconsistency — reload the page.
MAPSTED-1093	ERR_METHOD_REMOVED	No	Method '{method}' was removed in Mapsted Maps JavaScript API {removedIn}. Migration: {migration}.	Follow the migration guide in the error message. See the Changelog.

---

Authentication — 1200–1299

Code	Symbolic name	Recoverable	Message template	Resolution
MAPSTED-1200	ERR_API_KEY_INVALID	No	API key is invalid or has been revoked.	Check your access key in the Mapsted Hub. Generate a new key if revoked.
MAPSTED-1201	ERR_API_KEY_EXPIRED	No	API key expired on {expiry}. Renew at developers.mapsted.com.	Log in to developers.mapsted.com and renew the key before the next deployment.

---

Network — 1300–1399

Code	Symbolic name	Recoverable	Message template	Resolution
MAPSTED-1310	ERR_CSP_FRAME_BLOCKED	No	Map iframe was blocked or failed to load. Embedding is governed by two CSP directives: (1) your page's CSP frame-src must allow the map origin '{expectedFrameSrc}'; (2) the Mapsted map app's CSP frame-ancestors must allow this page's origin '{parentOrigin}'. If your site is not on a *.mapsted.* domain the map app may be refusing the embed — contact Mapsted.	Add the Mapsted domain to your page's Content-Security-Policy: frame-src directive. Example: frame-src https://mapi.mapsted.com. If your site is not on a *.mapsted.* domain, contact Mapsted so the map app's frame-ancestors directive can allow your origin.

---

Security config — 1300–1399

Code	Symbolic name	Recoverable	Message template	Resolution
MAPSTED-1303	ERR_SECURITY_CONFIG_ORIGIN_MISMATCH	No	SecurityConfig rejected message from origin '{origin}'. Expected one of: {expected}.	A postMessage was received from an origin not in the security.allowedOrigins + security.additionalOrigins whitelist. Verify your security config in InitOptions or add the origin to additionalOrigins.

Note: In production the expected field (the full origin whitelist) is redacted from the error message to prevent origin disclosure. Pass strict: true in InitOptions during development to see the unredacted value.

---

Security — 1400–1409

Code	Symbolic name	Recoverable	Message template	Resolution
MAPSTED-1400	ERR_ORIGIN_NOT_ALLOWED	No	Message from origin '{origin}' rejected. Expected '{expected}'.	A postMessage was received from an unexpected origin. This may indicate a misconfigured mapsDomain or a security intrusion attempt. Verify your mapsDomain value.

Note: In production the expected field is redacted from the error message to prevent origin disclosure. Enable strict mode (setStrictMode(true)) in development to see the full value.

---

AI Assistant — 1500–1509

The MAPSTED-1500–MAPSTED-1509 range is reserved for a future release. The AI assistant is not available in 4.0.1, so these codes are not emitted by the current release.

---

Error code ranges summary

Range	Category
1000–1009	Initialisation
1010–1019	Configuration
1020–1029	Iframe / DOM
1030–1039	Communication (postMessage)
1040–1049	Navigation
1050–1059	Quota
1060–1069	POI / Entity
1070–1079	Wayfinding / Routing
1080–1089	Overlays and UI
1090–1099	API state
1200–1299	Authentication
1300–1399	Network / Security config
1400–1409	Security (origin)
1500–1509	AI Assistant

---

Related pages

• Complete API Reference
• Type Definitions — MapState, ApiState
• Changelog — error codes