API response wrapping needs consistent error semantics

What the public implementation shows

Guevara includes response models, API response filters, exception filters, validation behavior, and typed domain exceptions.

The HTTP layer translates application and domain outcomes into one externally consistent response shape. This is the implementation fact behind the note; the architectural reading begins from that visible boundary rather than from an assumed production story.

Operating principleConsistency at the API edge reduces ambiguity only when error meaning remains specific.

The decision behind the mechanism

Central translation prevents every controller from inventing status codes and error bodies while preserving typed failure categories.

A universal 200 response or generic 500 body can erase the distinction between caller correction, access denial, missing state, and platform failure. The mechanism matters because it gives that failure a named boundary, durable evidence, and a controlled response instead of leaving the outcome to timing or operator guesswork.

• Map typed exceptions to stable HTTP and error codes.
• Keep validation detail structured.
• Never leak stack traces or sensitive values.
• Carry correlation context into error responses.

How the control should be operated

The contract should define stable error codes, safe messages, correlation context, validation detail, HTTP status, and logging behavior.

Clients can recover predictably and operators can classify failures from evidence instead of response text. The reusable lesson is not to copy a class or endpoint in isolation, but to preserve the relationship between identity, state, authority, evidence, and operational ownership.