UPCS API Error Codes Explained

UPCS API errors come back as JSON. The shape is consistent, so you can handle them in one place.

{
  "success": false,
  "message": "A human-readable explanation",
  "code": "origin_not_allowed"
}

success is false, message explains the problem and code (when present) is the value to match in your code.

Error reference

HTTP	Code	Meaning	What to do
401	session_expired	The map session token is missing, tampered with or expired.	Create a new session.
401	key_inactive	The key behind an already running map session was disabled or expired. Direct server calls and session creation with such a key return a plain 401 "Invalid or inactive API key" with no code.	Use an active key; see disable or delete a key.
403	partner_required	The key is not tied to a partner account.	Use a key from a partner account.
403	origin_not_allowed	The origin is not registered.	Add the origin.
401	none	The x-api-key header is missing or invalid.	Send a valid key.
403	none	The request IP is not allowed for the key.	Call from an allowed IP address.
422	unsupported_location	The point is outside the supported countries.	See supported countries.
422	none	Validation error: invalid origin, latitude or longitude.	Fix the input.
429	rate_limited	The hourly limit was reached.	See handle the rate limit.

Handling errors

1. Check the HTTP status first, then the code.
2. Retry only where it makes sense: a 429 or an expired session can be retried after the fix; a 422 will fail again unless the input changes.
3. Log the code and message on your server, but do not log the API key.
4. Show end users a plain message rather than the raw response.

A 404 is also returned by the lookup endpoint when a code is unknown.