Design a consistent API error handling and input validation system with structured error responses, validation middleware, and client-friendly error messages.
## ROLE You are a backend architect obsessed with developer experience who believes that an API's error responses are just as important as its success responses. You have seen firsthand how unclear error messages lead to hours of wasted developer time and support tickets. You design error systems where developers can identify the problem, understand why it happened, and fix it — all from the error response alone, without contacting support. ## CONTEXT Error handling is the most impactful aspect of API developer experience yet the most frequently neglected. When everything works, all APIs feel the same. When something breaks, the quality of the error response determines whether the developer fixes the issue in 30 seconds or wastes 2 hours. A well-designed error system returns machine-readable error codes, human-readable messages, field-level validation details, and enough context to diagnose the issue without access to server logs. ## TASK Design a complete error handling and validation system: 1. **Error Response Schema**: Design a universal error response format used by every endpoint. Include: HTTP status code, machine-readable error type/code, human-readable title and detail, field-level errors for validation failures, a request ID for correlation, and a documentation URL for the specific error. 2. **Error Taxonomy**: Create a categorized error code system: AUTH_* for authentication/authorization errors, VALIDATION_* for input validation, RESOURCE_* for resource state errors, RATE_* for rate limiting, and INTERNAL_* for server errors. Define 20-30 specific error codes covering common scenarios. 3. **Validation Middleware**: Design a validation layer that validates request bodies, query parameters, path parameters, and headers before the request reaches business logic. Show the implementation using a schema validation library (Zod, Joi, or class-validator) with custom error formatting. 4. **Business Rule Errors**: Design how to handle errors that are not validation errors but business logic failures (e.g., insufficient funds, conflicting schedule, expired invitation). These should return specific error codes with actionable messages. 5. **Partial Success Handling**: For batch endpoints that process multiple items, design the partial success response format: which items succeeded, which failed and why, and whether the operation was atomic or best-effort. 6. **Error Localization**: Design a system for returning error messages in the client's language based on Accept-Language header, with fallback to English. 7. **Error Logging & Monitoring**: Design the server-side error handling that captures: full request context, stack traces (for 5xx only), user context, and request timing. Configure alerting thresholds by error type. 8. **Client-Side Error Handling Guide**: Write a guide showing consumers how to build a robust error handler that: checks status codes, parses the error response, displays field-level errors on forms, shows user-friendly messages for known errors, and reports unknown errors. ## INFORMATION ABOUT ME - [API FRAMEWORK] (Express, Fastify, Django, FastAPI, Spring Boot) - [VALIDATION LIBRARY PREFERENCE] - [CURRENT ERROR RESPONSE FORMAT IF ANY] - [LANGUAGES TO SUPPORT FOR ERROR MESSAGES] ## RESPONSE FORMAT Deliver the error schema specification, validation middleware code, error handler middleware code, and a client-side error handling example. Include a complete error code reference table.
Or press ⌘C to copy
Replace these placeholders with your own content before using the prompt.
[API FRAMEWORK][VALIDATION LIBRARY PREFERENCE][CURRENT ERROR RESPONSE FORMAT IF ANY][LANGUAGES TO SUPPORT FOR ERROR MESSAGES]