Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Diagnostics

Use This When

Use this page before building product screens or when an integration fails in a new environment.

What You Will Build

You will build a diagnostics screen that separates API reachability, readiness, and authentication problems.

What Must Already Be True

  • Public API base URL is configured.
  • The shared API Client exists.
  • The application can tell whether a user is signed in.

API Contract

Public operational endpoints:

GET /healthz
GET /readyz

Suggested response types:

export type HealthResponse = {
  status: string;
  release?: string;
  runtime?: {
    git_sha?: string;
    image_ref?: string;
    fly_app_name?: string;
    fly_process_group?: string;
    fly_region?: string;
  };
};

export type ReadinessResponse = {
  status: string;
  release?: string;
  runtime?: HealthResponse["runtime"];
  checks?: Array<{
    name: string;
    ok: boolean;
    detail?: string;
  }>;
};

Load public diagnostics:

export async function loadApiDiagnostics(client: KycApiClient) {
  const [health, readiness] = await Promise.all([
    client.get<HealthResponse>("/healthz"),
    client.get<ReadinessResponse>("/readyz")
  ]);

  return { health, readiness };
}

After sign-in, verify one protected endpoint that matches the product you are building.

UI States

StateMeaningUser action
ReachableBrowser can call public API endpoints.Continue setup.
Not reachableNetwork, base URL, CORS, or DNS may be wrong.Check API base URL and frontend origin.
ReadyAPI reports it can handle work.Continue product flow.
DegradedAPI is reachable but not fully ready.Show diagnostics and retry later.
AuthenticatedUser token is present and accepted.Enable protected flows.
UnauthorizedToken is missing, expired, or invalid.Sign in again.

Developer diagnostics should show the API release, deployment/runtime metadata, and any failed readiness check names. Do not show /metrics in customer-facing UI; it is an operator/debug endpoint.

Implementation Steps

  1. Add a diagnostics route or admin-only panel.
  2. Call /healthz and /readyz without requiring sign-in.
  3. Show configuration, reachability, readiness, and auth as separate rows.
  4. After sign-in, call one protected endpoint and show whether the token works.
  5. Include request_id when a protected diagnostic request fails.

Checkpoint

  • A developer can diagnose base URL, readiness, and auth problems without opening browser devtools.
  • A developer can compare the frontend environment against the backend release currently serving the API.
  • The diagnostics page does not expose private credentials or regulated data.

Common Mistakes

  • Hiding diagnostics behind the same auth problem being diagnosed.
  • Calling only protected endpoints and missing CORS or readiness failures.
  • Showing raw tokens in debug output.
  • Treating degraded readiness as a user input error.