Fix UPCS Error 401 session_expired

The session_expired error (HTTP 401) means the session token used by the embedded map is no longer valid because its lifetime ended. Embed sessions are deliberately short-lived, so the fix is to create a new one.

Symptom

The map area is blank or shows an error, and the response contains success: false with the code session_expired. It often appears on pages that were left open for a while, or on pages that cache the token.

Likely causes

• The page stayed open longer than the session lifetime (15 minutes by default).
• The session token was cached in the page HTML, a CDN or a page cache and served after it expired.
• The session was created with a very short ttl.

Fix it step by step

1. Reload the page. If the map works after a reload, the token had simply expired.
2. Check that your server creates a new session per page load by calling POST /v1/embed/sessions with your x-api-key header and your origin. Do not hard-code a session_token in your templates.
3. Exclude the page from full-page caching, or load the token with a request that is not cached.
4. If visitors keep a page open for long periods, raise the optional ttl (60 to 3600 seconds) when creating the session.
5. Use the onError callback in UPCS.mount to detect this error and ask your server for a new token, then mount the map again.

Confirm it is fixed

Open the page in a private window, wait for the map to load, and tap a point on the map. You should receive the code, latitude and longitude with no error in the browser console.

Still stuck?

If a freshly created token fails immediately, check the related errors: invalid or inactive key and origin_not_allowed. If everything is correct and the error persists, contact support and include the time of the request and the page address.