Design a consistent, actionable, machine-readable API error model that clients can handle reliably.
## CONTEXT I need a consistent error model for my API in 2026 because inconsistent errors are one of the biggest sources of integration pain. Clients need errors that are machine-readable for branching logic and human-readable for debugging, with stable error codes that survive message wording changes. Many APIs return bare status codes, leak stack traces, or use ad-hoc shapes that differ per endpoint, forcing clients into brittle string matching. I want a unified error contract, ideally aligned with RFC 9457 Problem Details, that covers validation, auth, rate limiting, and server faults coherently and is safe to expose publicly. ## ROLE Act as an API design specialist focused on the client integration experience. You have debugged countless integrations and know exactly what information a client needs in an error and what must never leak. ## RESPONSE GUIDELINES - Start with the canonical error envelope and a concrete example for each major category. - Recommend stable, namespaced error codes separate from human messages. - Justify what is included and, crucially, what is deliberately excluded for security. - Map error categories to HTTP status codes precisely. - Address both the wire format and the internal discipline to keep it consistent. ## TASK CRITERIA ### 1. Error Envelope Design - Define the canonical error body, ideally based on RFC 9457 Problem Details. - Include a stable error code, human message, and a documentation link or type. - Add a request/trace ID so clients can reference issues in support. - Decide whether and how to return multiple errors at once. ### 2. Error Taxonomy & Codes - Design a namespaced, stable error-code scheme decoupled from messages. - Map categories (validation, auth, not-found, conflict, rate-limit, server) to codes. - Ensure codes are granular enough for clients to branch on meaningfully. - Document the full code catalog format for the API reference. ### 3. Validation Errors - Design field-level validation errors with paths and reasons. - Make validation errors aggregatable so clients fix everything at once. - Specify localization strategy for human-readable messages if needed. - Distinguish input validation from business-rule violations. ### 4. Status Code Mapping & Security - Map each error category to the correct HTTP status code consistently. - Define what must never appear in errors (stack traces, internal IDs, secrets). - Address how auth errors avoid leaking whether resources exist. - Specify behavior for unexpected/unhandled server errors. ### 5. Consistency Enforcement - Recommend a central error-handling layer to guarantee shape consistency. - Provide contract tests asserting error structure across endpoints. - Document the error model prominently for client developers. - List error anti-patterns to ban (200-with-error-body, inconsistent shapes). ## ASK THE USER FOR - The API style and framework, and any existing error format in use. - The client types consuming errors and their handling needs. - Whether errors are public-facing and any data-leakage constraints. - Localization and multi-error requirements.
Or press ⌘C to copy