MyClub/DOCS/ERROR_CENTER_API.md

Error Center API

Centralized error reporting across frontend (TS/TSX), backend (Go), and infra (future: Docker). This document specifies the request/response schema and endpoints implemented in this repository so you can integrate additional producers and build the admin UI.

Overview

• Public ingest endpoint: POST /api/v1/errors
• Admin browsing: GET /api/v1/admin/errors, GET /api/v1/admin/errors/:id
• Storage model: error_events table via GORM model ErrorEvent
• Capture hooks in-app:
  • Backend: panic recovery + 5xx response reporter
  • Frontend: window.onerror, unhandledrejection, React ErrorBoundary, Axios 5xx interceptor
• Rate limiting: per-IP+path, applied to ingest endpoint

Data Model: ErrorEvent

Returned by admin endpoints. JSON field names match below.

{
  id: number,
  created_at: string,            // ISO timestamp (ingestion time)
  updated_at: string,            // ISO timestamp
  origin: string,                // e.g. "frontend" | "backend" | "docker"
  language: string,              // e.g. "ts" | "tsx" | "go"
  severity: string,              // e.g. "error" | "warn" | "fatal"
  message: string,
  stack: string,
  component: string,
  file: string,
  line: number,
  column: number,
  url: string,
  method: string,                // HTTP method when applicable
  status: number,                // HTTP status when applicable
  request_id: string,            // correlates backend <-> frontend
  user_id: number | null,
  session_token: string,
  tags: object,                  // JSON map (string -> string)
  context: object,               // JSON map (string -> any)
  env: string,                   // e.g. "development" | "production"
  version: string,
  hostname: string,
  occurred_at: string            // ISO timestamp of when error actually happened
}

Endpoint: POST /api/v1/errors (Public ingest)

Ingests a single error event.

• Method: POST
• Path: /api/v1/errors
• Headers:
  • Content-Type: application/json
  • Optional: Authorization: Bearer <token> (not required by default; used if you proxy to external collectors)
• Rate limit: 120 requests per minute per IP+path. On limit exceeded: 429 Too Many Requests and Retry-After header (seconds).

Request body (JSON)

{
  origin: string,                        // required, e.g. "frontend" | "backend" | "docker"
  language?: string,                     // e.g. "ts" | "tsx" | "go"
  severity?: string,                     // "error" | "warn" | "fatal" (default depends on sender)
  message: string,                       // required
  stack?: string,
  component?: string,
  file?: string,
  line?: number,
  column?: number,
  url?: string,
  method?: string,
  status?: number,
  request_id?: string,
  user_id?: number,
  session_token?: string,
  tags?: { [k: string]: string },
  context?: { [k: string]: any },
  env?: string,
  version?: string,
  hostname?: string,
  occurred_at?: string                   // ISO (RFC3339). Defaults to server time if omitted
}

Responses

• 201 Created

{ "id": <number> }

• 400 Bad Request (invalid JSON/payload)

{ "error": "invalid payload" }

• 429 Too Many Requests (rate limited)

{ "error": "Příliš mnoho požadavků, zkuste to prosím později." }

• 500 Internal Server Error (storage issue)

{ "error": "failed to store" }

cURL example

curl -X POST http://localhost:8080/api/v1/errors \
  -H 'Content-Type: application/json' \
  -d '{
    "origin":"frontend",
    "language":"tsx",
    "severity":"error",
    "message":"TypeError: cannot read properties of undefined",
    "stack":"at Component (App.tsx:42:7)",
    "url":"/admin/errors?filter=today",
    "method":"GET",
    "status":500,
    "request_id":"b28a8a2b-2f3d-452a-9a5d-1ec74e53a2d4",
    "context": {"userAgent":"...","viewport":{"w":1440,"h":900}},
    "env":"development",
    "occurred_at":"2025-11-06T12:00:00Z"
  }'

Endpoint: GET /api/v1/admin/errors (Admin list)

Lists error events with filtering and pagination.

• Method: GET
• Path: /api/v1/admin/errors
• Auth: Admin role required (standard admin authentication of this app)
• Query params:
  • origin: string (exact match: frontend | backend | docker)
  • severity: string (exact match: fatal | error | warn)
  • method: string (exact match: GET | POST | PUT | PATCH | DELETE)
  • status: number (exact match HTTP status)
  • search: string (substring, ILIKE on message, stack, url)
  • from: string (RFC3339, filters occurred_at >= from)
  • to: string (RFC3339, filters occurred_at <= to)
  • page: number (default 1, min 1)
  • limit: number (default 20, min 1, max 200)

Response

• 200 OK

{
  "items": [ ErrorEvent, ... ],
  "total": <number>
}

Example

curl -b cookies.txt \
  'http://localhost:8080/api/v1/admin/errors?origin=frontend&severity=error&search=TypeError&page=1&limit=50'

Endpoint: GET /api/v1/admin/errors/:id (Admin detail)

Returns a single error event by ID.

• Method: GET
• Path: /api/v1/admin/errors/:id
• Auth: Admin role required

Responses

• 200 OK — returns the ErrorEvent JSON
• 404 Not Found — { "error": "not found" }
• 500 Internal Server Error — { "error": "failed to load" }

Built-in Producers (in this repo)

• Frontend reporter (src/services/errorReporter.ts)

  • Sends errors to /api/v1/errors by default
  • Uses localStorage overrides when present:
    • fc_error_ingest_url, fc_error_ingest_token
  • Or build-time env vars:
    • REACT_APP_ERROR_INGEST_URL, REACT_APP_ERROR_INGEST_TOKEN
  • Installed in index.tsx:
    • Global handlers: window.onerror, unhandledrejection
    • ErrorBoundary calls reporter on render errors
  • Axios 5xx interceptor (src/services/api.ts) reports server errors

• Backend reporter (internal/services/error_reporter.go)

  • Panic recovery middleware and 5xx status reporter send events
  • Destination:
    • If ERROR_INGEST_URL configured, report to that URL with ERROR_INGEST_TOKEN if set
    • Otherwise, fallback to this server’s public API base + /errors

Configuration

• Backend env:
  • ERROR_INGEST_URL (optional): external collector URL
  • ERROR_INGEST_TOKEN (optional): bearer token for external collector
• Frontend runtime overrides (optional):
  • localStorage.setItem('fc_error_ingest_url', 'https://example.com/ingest')
  • localStorage.setItem('fc_error_ingest_token', 'YOUR_TOKEN')
• Defaults require no configuration; all errors post to this app at /api/v1/errors.

Correlation and Metadata

• X-Request-ID header is exposed; frontend interceptor forwards it in payload as request_id.
• occurred_at denotes when the error happened; created_at is ingestion time.
• tags is a flat string map; context allows arbitrary structured metadata.

Rate Limiting Details (Ingest)

• Scope: per client IP and request path
• Window: 60 seconds
• Max: 120 requests per window
• Exceeding limit: 429 Too Many Requests with Retry-After (seconds remaining)

Notes

• CORS: The ingest endpoint follows the app’s global CORS configuration.
• PII: Consider redacting sensitive data before sending in message, stack, context.
• Deduplication: The frontend reporter applies a basic burst de‑duplication (1.5s window) client-side; server stores all events.

---

Last updated: 2025-11-06