UPCS API Error Codes Reference

UPCS API errors are JSON objects with success: false, a human-readable message and, for many failures, a machine-readable code. Branch on code and HTTP status, not on the message text.

{
  "success": false,
  "message": "This origin is not registered for your partner account. Add it in your partner panel.",
  "code": "origin_not_allowed"
}

Reference

Status	Code	Meaning	What to do
401	session_expired	The embed session token is missing, invalid or expired	Create a new session and remount
401	key_inactive	The key behind a running embed session was disabled or expired (seen only on a running map, via onError)	Re-enable or use another key, then create a new session
401	none	x-api-key missing, or wrong, disabled or expired ("Missing API key" or "Invalid or inactive API key"); also returned when creating a session	Check the header and key value, and that the key is active
403	partner_required	The key is not linked to a partner account	Create a partner account and use a key from its panel
403	origin_not_allowed	Origin not registered for the key	Add it under Allowed origins
403	none	The caller's IP is not allowed for the key	Allow the server IP or use the right host
422	unsupported_location	The point is outside supported countries	Fall back to a normal address
422	none	Validation error, such as invalid origin, lat or lng	Fix the input
429	rate_limited	Hourly limit exceeded	Back off and retry later

The lookup endpoint reports a malformed code with 400 and an unknown code with 404; its error body uses error and message fields.

Handling pattern

async function callUpcs(url, options) {
  const res = await fetch(url, options);
  if (res.ok) return res.json();

  const body = await res.json().catch(() => ({}));
  const err = new Error(body.message || 'UPCS error');
  err.status = res.status;
  err.code = body.code;
  throw err;
}

Then decide per code: refresh a session, alert an operator, or show a message.

Related guides

• Handle onError and session_expired
• Allowed origins explained
• Handling unsupported_location
• Rate limits and backoff

Log the status, code and endpoint for every failure; that single habit makes most integration problems quick to diagnose.