Skip to content

Usage Statement Period Not Covered

URI: https://docs.ankatech.co/errors/usage-statement-period-not-covered
HTTP Status: 422 Unprocessable Content

When you see this

You asked for a signed usage statement for a month that ends before the first day whose rows this deployment's usage store holds. The request is refused and nothing is written.

The first covered day is the later of:

  • the day this deployment was installed — the installer writes it once, into the deployment's integrity-protected trial sentinel, in the same run that creates the usage store; and
  • the oldest day retention still keeps (LICENSE_USAGE_RETENTION, two years by default) — older per-day rows have been deleted.

It is the same coveredFrom the telemetry read publishes in rangeCompleteness.

Why the month is refused rather than stated as empty

A statement's completeness declaration names the days of its month that recorded no usage. Before the first covered day there is no row either because the deployment did not exist yet or because retention deleted it; in both cases 'no row' is not evidence of no usage. Stating such a month would sign that falsehood, and an issued statement is never rewritten: the false declaration would be permanent.

A month that contains the first covered day is issuable: its declaration carries completeness.coveredFrom and partitions only the days from it. Days before it appear in neither daysWithRows nor daysWithoutRows.

Why 422 and not 409

The sibling statement refusals are 409 because each resolves when something about the resource changes — a month finalizes, a correction names what it supersedes. This one never resolves: the installation day does not move back, and retention only moves forward. Every parameter is well formed; what fails is the relationship between the requested month and the deployment's coverage.

Response Example

{
  "type": "https://docs.ankatech.co/errors/usage-statement-period-not-covered",
  "title": "Usage Statement Period Not Covered",
  "status": 422,
  "detail": "A signed usage statement is issued only over a month whose rows this deployment's usage store holds; 2024-10 ends before 2026-09-27, the first day the store covers (the later of the day this deployment was installed and the oldest day retention keeps). Before it there is no row either because the deployment did not exist yet or because retention deleted it, and in both cases 'no row' is not evidence of no usage, so no statement can declare this month's completeness. State a month from 2026-09 on.",
  "instance": "/api/v3/admin/usage/statements",
  "extensions": {
    "requestId": "4c1e8a27-93b0-4d5f-a6e2-0f7d91b3c258"
  }
}

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details.

The refusal is raised by the licence server and reaches you through the Admin API unchanged: 422 is a member of {400, 402, 404, 409, 422}, the set the relay propagates with its own type, title, detail and status. The detail names the month and the first covered day, and no figure.

How to Resolve

  1. Read the first covered day. GET /api/v3/admin/usage/telemetry returns rangeCompleteness.coveredFrom; the detail of this refusal names the same day.
  2. State a month from the one holding that day on. The month holding it is issuable once it is FINAL, and declares only its covered days.
  3. Do not retry the refused month. It will never become issuable on this deployment.

For full schema definitions, examples, and interactive testing, see the Developer Hub Reference.

* restricted content — see higher-tier documentation