feat(api): tag each error with a ref and count errors by service

Every structured error carries a short ref, appended to its message and logged with the request; /api/dashboard/status gains per-service error counts. Gzip now compresses in place.

docs/dev/rest-api/dashboard.md

@@ -43,7 +43,7 @@ All are `GET`.
 
 | Path | Returns |
 |------|---------|
-| `/api/dashboard/status` | Version, `code_hash`, bind host and port, `mode` (`full`, `api_only`, `remote_only`), uptime, `requests_total`, `requests_rejected` (401s), `requests_by_key` (label → count), configured service count (the same services as `/api/dashboard/services`), session count, `max_sessions` (`null` when the operator configured no limit), `session_ttl`, job counts by status. The service count includes services that failed to import - use `/api/dashboard/services` for the number that loaded. |
+| `/api/dashboard/status` | Version, `code_hash`, bind host and port, `mode` (`full`, `api_only`, `remote_only`), uptime, `requests_total`, `requests_rejected` (401s), `requests_by_key` (label → count), `errors` (error counts by service tag, then by `error_code`), configured service count (the same services as `/api/dashboard/services`), session count, `max_sessions` (`null` when the operator configured no limit), `session_ttl`, job counts by status. The service count includes services that failed to import - use `/api/dashboard/services` for the number that loaded. |
 | `/api/dashboard/sessions` | Every live remote session: `id`, `owner` (username or masked key), `creator_ip`, `service`, `title_id`, `titles`, `tracks`, `title` (the display name of the title the client is on: the last one it asked tracks for, else the first resolved title), `auth_status`, `auth_error`, `server_account` (the server profile lent to the remote session, else `null`), `server_cdm` (`false` when the client's own device licenses the remote session), `server_cdm_max_height` (the tallest video the server CDM licenses live, else `null`), `client`, `actions`, `created_at` and `last_accessed` (ISO 8601) with `created_ts` and `last_accessed_ts` (Unix epoch, the same clock as log `ts`), `age_seconds`, `idle_seconds`, `log_seq`. `client` is whatever the remote client sent as `client` in its session create request. The CLI sends `version`, `code_hash` (the commit the client runs, `null` when its source cannot be read), `platform` and `argv`. `argv` is the command line the user ran: proxy and URL userinfo, secret query parameters and credential values become `***`, home and install paths shorten as in the logs, and the line is cut at 3000 characters. An older client sends less or nothing and the field is `{}`. `log_seq` is the last sequence number in the remote session's service log - poll `/api/dashboard/sessions/{id}/logs` when it changes. `actions` is the session's request log, newest last, capped at 500: `ts`, `method`, `action` (`titles`, `tracks`, `segments`, `license`, `prompt`, …), `query`, `status`, `ms`, `bytes_in`, `bytes_out`. |
 | `/api/dashboard/jobs` | Every download job with full detail, regardless of owner. Empty in `--remote-only` mode. |
 | `/api/dashboard/logs` | `{"seq": N, "records": [...]}`: the last 1000 log records. `?since=<seq>` returns only newer records; `?level=WARNING` sets the minimum level; `?logger=serve` keeps one logger and its children (`aiohttp.access` is the noisiest). `ts` is a Unix epoch in seconds. |
@@ -54,6 +54,11 @@ All are `GET`.
 | `/api/dashboard/health` | Preflight: whether this instance could finish a download. Cached 30 seconds. |
 | `/api/dashboard/events` | Server-Sent Events stream. With `?since=<seq>` it returns `{"seq", "stats", "events": [...]}` instead: every event after `seq` (the server keeps the last 20000, log records included, so a poll every few seconds is safe even under a busy access log) as one JSON burst, so a UI that polls every few seconds still sees a remote session that opened and closed in between. |
 
+`errors` counts every structured error response since the server started, for example
+`{"EXAMPLE": {"SERVICE_ERROR": 4}, "-": {"SESSION_NOT_FOUND": 1}}`. The service is the one of
+the remote session, else the `service` field of the JSON body. `-` holds an error with no
+installed service. Each error also logs its [`ref`](errors.md#find-an-error-from-its-ref).
+
 `requests_rejected` counts 401 responses; those never appear in `requests_by_key`. The
 label is the `username` from the `users` entry when one is set, else the first four
 characters of the API key.

docs/dev/rest-api/errors.md

@@ -25,7 +25,8 @@ A structured error is always a JSON object with `status` set to the literal stri
 {
   "status": "error",
   "error_code": "INVALID_PARAMETERS",
-  "message": "vcodec must be one of: H264, H265, ...",
+  "message": "vcodec must be one of: H264, H265, ... (ref 7f3a2c)",
+  "ref": "7f3a2c",
   "timestamp": "2026-07-03T12:34:56.789012+00:00",
   "details": { "field": "vcodec" },
   "retryable": true,
@@ -40,7 +41,8 @@ A structured error is always a JSON object with `status` set to the literal stri
 |---|---|---|---|
 | `status` | string | Yes | Always the literal `"error"`. Lets a client distinguish an error body from a success body at a glance. |
 | `error_code` | string | Yes | A stable, machine-readable code from the [catalogue below](#error-code-catalogue). Match on this, not on `message`. |
-| `message` | string | Yes | A human-readable description of what went wrong. Wording may change between versions, so do not parse it. |
+| `message` | string | Yes | A human-readable description of what went wrong, followed by `(ref <ref>)`. Wording may change between versions, so do not parse it. |
+| `ref` | string | Yes | A short random reference for this one error. The server logs it with the request, so an operator can find the record from a user's report. |
 | `timestamp` | string | Yes | ISO 8601 timestamp (UTC) of when the error response was built. |
 | `details` | object | Only when non-empty | Structured, error-specific context (for example the invalid field, a list of available titles, or the set of currently active jobs). |
 | `retryable` | boolean | Only when `true` | Present and set to `true` when retrying the same request may succeed later (network blips, rate limiting, transient outages). Absent otherwise. |
@@ -52,6 +54,17 @@ A structured error is always a JSON object with `status` set to the literal stri
     every code maps to a default status (see the catalogue), and the pairing is
     stable across releases.
 
+### Find an error from its `ref`
+
+For each error response, the server logs one `WARNING` line on the `api` logger:
+
+```text
+Error ref 7f3a2c: SERVICE_ERROR 422 POST /api/session/<id>/license service=EXAMPLE user=alice: Licence request failed: ...
+```
+
+Search the server log for `Error ref <ref>`. The handler's traceback, when there is one,
+is directly above that line. The [developer dashboard](dashboard.md) log view also shows it.
+
 ### The `details` object
 
 When present, `details` carries extra context specific to the error. It is only