Handle onError and session_expired

Embed sessions are deliberately short-lived, so a page left open for a while will eventually hit session_expired (HTTP 401). Handling it well means the visitor sees a friendly prompt, not a dead map.

Detect the error

onError receives an object with status, code and message. Check its code, and log the rest:

let map;

async function startMap() {
  const r = await fetch('/upcs-session');
  const { session_token } = await r.json();

  map = UPCS.mount('#upcs-map', {
    sessionToken: session_token,
    height: '500px',
    onSelect: handleSelect,
    onError: handleError
  });
}

function handleError(err) {
  console.error('UPCS error', err);
  if (err && err.code === 'session_expired') {
    refreshMap();
  } else {
    showMessage('The map could not be loaded. Please try again.');
  }
}

async function refreshMap() {
  if (map) map.destroy();
  showMessage('Refreshing the map...');
  await startMap();
}

Other codes you may receive include network_error and map_unavailable; keep a generic fallback message for anything you do not handle.

Other errors you may see

• key_inactive (401): the key behind the running map session was disabled or has expired. Fix it in the partner panel; retrying will not help.
• origin_not_allowed (403): the page's origin is not registered. See allowed origins explained.
• rate_limited (429): too many requests; see rate limits and backoff.

The complete list is in the error codes reference.

Avoid refresh loops

If creating a new session also fails, stop. Count attempts and give up after two or three, then show a message with a manual retry button. A loop that hammers your session endpoint will consume the key's hourly allowance.

Protect the user's work

Do not clear form fields when you remount. If the visitor already selected a location, keep the stored code in your form; the map is only the picker. For tuning the lifetime itself, see embed session TTL and renewal.