When to activate
- Designing error response format for new APIs
- Standardizing error codes across microservices
- Creating error documentation for API consumers
- Implementing global error handling middleware
- Mapping domain errors to HTTP status codes
When NOT to use
- For client-side error display/UI
- For logging and observability setup
- For exception tracking tool integration
Instructions
- Define error schema. Standard format:
{ error: { code, message, details, requestId, docsUrl } }.
- Map HTTP status codes. 400=validation, 401=auth, 403=permission, 404=not found, 409=conflict, 422=unprocessable, 429=rate limit, 500=server error.
- Create error code catalog. Machine-readable codes:
VALIDATION_ERROR, RESOURCE_NOT_FOUND, RATE_LIMIT_EXCEEDED, etc.
- Design validation errors. Return field-level errors:
{ field: "email", message: "must be valid email", code: "INVALID_FORMAT" }.
- Add request context. Include
requestId for debugging, timestamp, and path in every error response.
- Link to documentation. Include
docsUrl pointing to relevant API docs for self-service resolution.
- Implement middleware. Global error handler that catches exceptions and formats to standard schema.
Example
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request body failed validation",
"details": [
{ "field": "email", "message": "must be a valid email address", "code": "INVALID_FORMAT" },
{ "field": "age", "message": "must be between 18 and 120", "code": "OUT_OF_RANGE" }
],
"requestId": "req_abc123",
"docsUrl": "https://api.example.com/docs/errors#VALIDATION_ERROR"
}
}
1---2name: error-handler-designer3description: Design consistent, actionable error response schemas with proper HTTP status codes and error categorization4allowed-tools: [Read, Write, Grep]5effort: medium6metadata:7 source: https://skillmd.com/skills/uitbreidenos/error-handler-designer8---910## When to activate1112- Designing error response format for new APIs13- Standardizing error codes across microservices14- Creating error documentation for API consumers15- Implementing global error handling middleware16- Mapping domain errors to HTTP status codes1718## When NOT to use1920- For client-side error display/UI21- For logging and observability setup22- For exception tracking tool integration2324## Instructions25261. **Define error schema.** Standard format: `{ error: { code, message, details, requestId, docsUrl } }`.272. **Map HTTP status codes.** 400=validation, 401=auth, 403=permission, 404=not found, 409=conflict, 422=unprocessable, 429=rate limit, 500=server error.283. **Create error code catalog.** Machine-readable codes: `VALIDATION_ERROR`, `RESOURCE_NOT_FOUND`, `RATE_LIMIT_EXCEEDED`, etc.294. **Design validation errors.** Return field-level errors: `{ field: "email", message: "must be valid email", code: "INVALID_FORMAT" }`.305. **Add request context.** Include `requestId` for debugging, `timestamp`, and `path` in every error response.316. **Link to documentation.** Include `docsUrl` pointing to relevant API docs for self-service resolution.327. **Implement middleware.** Global error handler that catches exceptions and formats to standard schema.3334## Example3536```json37{38 "error": {39 "code": "VALIDATION_ERROR",40 "message": "Request body failed validation",41 "details": [42 { "field": "email", "message": "must be a valid email address", "code": "INVALID_FORMAT" },43 { "field": "age", "message": "must be between 18 and 120", "code": "OUT_OF_RANGE" }44 ],45 "requestId": "req_abc123",46 "docsUrl": "https://api.example.com/docs/errors#VALIDATION_ERROR"47 }48}49```