Skip to main content

Errors and support

MERGED, NOT DEPLOYED — the API returns a stable error code and correlation ID, not backend exception text. Fastify generates a UUID for each request. The response header x-correlation-id, error body's correlationId and log field reqId identify the same request. A:apps/api/src/app.ts:26-35,153-164,189-190 A:apps/api/src/common/stable-error.filter.ts:17-34

The browser uses friendly sentences and a reference. Inline PDF previews have fixed refusal pages for ended sessions, missing permission and missing files; unexpected failures add the reference. A:apps/api/src/app.ts:37-77 A:.set/work/decisions-2026-10-26.md:24-25

Support procedure (read-only):

  1. Ask for the reference, approximate time, screen and action. Do not request session cookies or credentials.
  2. Search the API log for that exact reqId around the reported time. LIVE ON STAGING — the observed log group is /set-nonprod/ecs, with 30-day retention. E:evidence-aws.md:69
  3. Read the matching request failed event and nearby request events. Record the stable code and safe diagnostic fields. Query strings and sensitive SDK properties are redacted; unexpected database errors are sanitized. A:apps/api/src/app.ts:14-24 A:apps/api/src/common/stable-error.filter.ts:27-65
  4. Follow the relevant operational action in runbooks. Never paste raw credentials or private answer/file content into a ticket.

Example Logs Insights query template; substitute the user's reference in the console. This query was not executed:

fields @timestamp, reqId, msg
| filter reqId = "REFERENCE_FROM_USER"
| sort @timestamp asc

NOT VERIFIED — a staging UI reference matched to its actual log event. Need an app evidence entry containing the sanitized reference check and deployed digest. The current Grafana read role is observed as metric-read only; Logs Insights access in the newer Terraform must not be assumed live. E:evidence-aws.md:30,95-96 I:infra/modules/security-alerts/main.tf:489-532

MERGED, NOT DEPLOYED — when there is no API response, the browser can generate a local reference. That reference cannot be promised to match a server log; support must also use time, action and network symptoms. A:apps/web/src/api.ts:110-167

LIVE ON STAGING — random request UUIDs and error-body correlationId exist in the deployed baseline. MERGED, NOT DEPLOYED — x-correlation-id response header, CORS exposure, friendly reference presentation and preview frame policy are wave-1 additions; the pack explicitly says the header is absent from develop. Support must not promise a header on the current staging release. E:evidence.md:54-55