api-error-contract-designerlisted

Create a stable error interface that clients can depend on without parsing prose. Preserve compatibility where practical and make every change explicit. ## Workflow 1. **Inventory current errors.** Trace handlers, middleware, validators, domain errors, and exception fallbacks. Record status, body shape, machine code, message source, retry behavior, and whether sensitive detail can leak. 2. **Define one envelope.** Use the repository's conventions where they exist; otherwise design a minimal shape such as: ```json { "error": { "code": "ORDER_ALREADY_PAID", "message": "This order has already been paid.", "request_id": "req_123", "fields": [{ "path": "email", "code": "INVALID_FORMAT" }], "retryable": false } } ``` Omit optional fields when irrelevant. Keep machine codes stable, uppercase, and domain-specific. 3. **Map semantics deliberately.** Assign statuses by protocol meaning: authentication, authorization, missing resource, conflict, validation, rate limit, upstream failure, and unexpected server error. Distinguish a safe retry from a permanent client error; add `Retry-After` only when the server can provide meaningful guidance. 4. **Separate public and internal detail.** Return safe messages. Log stack traces and internal context with the same request or correlation ID. Never expose SQL, filesystem paths, tokens, provider payloads, or raw exceptions. 5. **Model field errors structurally.** Use stable field path