Skip to content

Usage Telemetry Unresolved

URI: https://docs.ankatech.co/errors/usage-telemetry-unresolved
HTTP Status: 502 Bad Gateway

When you see this

A usage call — the usage figures, an export job, or a signed monthly statement — could not be answered, because the Admin API could not obtain an answer from the deployment's licence server.

On the usage figures, this is not a report of zero usage, and the detail says so in those words. That distinction is the reason this problem type exists: a billing screen that rendered 0 here would be stating a commercial fact the platform never measured. An export, statement or key call withholds no usage figure, so its detail names what could not be done and denies nothing.

Why every unreadable outcome converges on one status

Other relayed surfaces in the Admin API answer 502 when an upstream is unavailable and 504 when a deadline elapses. The usage surfaces deliberately do not make that split. A figure that could not be read is the same fact to a chargeback report whichever way the read failed, and a caller that had to learn to treat two statuses identically would eventually treat one of them as data. So an unavailable licence server, an elapsed deadline, an upstream 401/403 on the platform's own service-to-service credential, and an upstream response the Admin API could not decode all arrive here, with the same recognisable type.

Two upstream outcomes are not relayed as this problem:

  • 400, 402, 404, 409 and 422 raised by the licence server about your request are propagated with their own type, title, detail and status — see Upstream Rejected Request. The 402 is Deployment License Expired.
  • One member of that propagate set is the exception: usage-plane-contract-violation. It reports a disagreement between the plane and the tenant filter that the Admin API itself composed, so it is this service's own contract violation and never a client error. It arrives here as a 502.

Common Causes

  • The licence server is down, restarting, or unreachable from the Admin API.
  • The licence server answered 5xx, or answered a body the Admin API could not decode.
  • The service-to-service credential was refused (401) or found insufficiently scoped (403) by the licence server. This is a deployment misconfiguration, not a statement about your authorization, so it is never re-presented as a 401 or 403.
  • The call exceeded its deadline.

The upstream is named by role in detail — "the licence server" — and never by address, host or transport identity. instance and the correlation id are always the Admin API's own.

Response Example

{
  "type": "https://docs.ankatech.co/errors/usage-telemetry-unresolved",
  "title": "Usage Telemetry Unresolved",
  "status": 502,
  "detail": "The licence server was unavailable, so no usage figure can be stated for this range. This is not a report of zero usage.",
  "instance": "/api/v3/admin/usage/telemetry"
}

Content-Type: application/problem+json. This type is emitted only by the Admin API, which carries its correlation identifier as extensions.requestId when it is present — never at the top level. See Error Index for where each service puts it.

How to Resolve

  1. Do not record the absence as zero. Re-present the refusal; a usage panel shows "could not be read", never 0.
  2. Check the licence server's health, then retry with exponential backoff. 502 classifies as a transient server error in the SDK and CLI.
  3. If the condition persists, the cause is usually deployment-side: the licence server is not running, or the Admin API's service-to-service credential for it is missing or under-scoped. Both are operator actions, not caller actions.
* restricted content — see higher-tier documentation