An API should translate internal failures into stable, non-sensitive problem responses while preserving detailed evidence in protected telemetry. Middleware is appropriate for concerns that truly wrap every request, such as correlation, timing, and selected security headers. Domain decisions and resource authorization do not belong in generic middleware.
In production, generate or validate identifiers using a strict format and connect them with distributed trace context. A client-provided ID is a correlation hint, never an identity or permission.
Record event name, timestamp, severity, route template, status, duration, trace ID, and safe application identifiers. Avoid authorization headers, cookies, request bodies, raw prompts, retrieved private text, database URLs, and stack traces in client responses. Central redaction should be backed by tests.
Return a generic 500 with a trace ID, record the original exception in protected logs, and let monitoring count it. Do not catch BaseException, cancellation signals, or process-exit events as ordinary application errors.
An AI operation spans API, queue, retrieval, provider, and tools. Propagate trace context across boundaries and record safe identifiers for the prompt, model, schema, and evaluation versions. Raw model context can contain personal or proprietary data; observability must be useful without becoming a second ungoverned dataset.
Add problem responses for validation, forbidden access, conflict, dependency timeout, and unexpected failure. Add a redaction test using a fake secret.
Acceptance criteria: every response includes a correlation ID, errors have stable types, and the fake secret appears nowhere in captured logs or bodies.