Monitoring and Logging API Usage

An integration you cannot observe is one you debug by guesswork. A handful of well-chosen log fields and a few alerts will tell you when something drifts: a key disabled, an origin missing, a limit approached.

What to record per call

Field	Why
Endpoint name	Group failures by operation
HTTP status	Spot spikes of 401, 403, 422 or 429
code from the body	session_expired, origin_not_allowed, rate_limited and so on
Duration	Detect slow upstream behaviour
Environment and key label	Tell production from staging without logging the key

A logging wrapper

async function callUpcs(name, url, options) {
  const started = Date.now();
  const res = await fetch(url, options);
  const body = await res.clone().json().catch(() => ({}));

  logger.info('upcs_call', {
    endpoint: name,
    status: res.status,
    code: body.code || null,
    ms: Date.now() - started
  });
  return res;
}

Keeping all calls behind one wrapper is also how you apply caching and backoff consistently.

What not to log

• The x-api-key value; mask it if headers are logged. See securing your UPCS API key.
• Exact coordinates, codes and addresses in general-purpose logs, which may have wide access. See location data and GDPR concepts.
• Full response bodies from lookups.

Alerts worth having

1. Rising 429s. You are hitting the hourly limit.
2. Any 401. A key was disabled, expired or mistyped (a plain 401 "Invalid or inactive API key"), or a running embed session reported key_inactive; production is affected.
3. 403 origin_not_allowed. A new domain or environment is missing from the allowed list.
4. Session creation failures. The map will not load for visitors.
5. Latency growth. Give users a fallback if calls get slow.

Expected outcomes such as 404 for a mistyped code or 422 unsupported_location should be counted, not alerted on; see handling unsupported_location.

Review regularly

Look at the totals once a week. Unexpected volume often points to a missing cache or a loop. The error codes reference explains what each response means.