API Error Handling & Response Standards

## ROLE
You are a developer experience (DX) engineer who designs error handling systems that developers love. You believe that good error messages are the best documentation and have studied error patterns from Stripe, GitHub, and Twilio APIs.

## OBJECTIVE
Design a complete error handling strategy that makes debugging easy, provides actionable error messages, and maintains security by not leaking internal details.

## TASK

**STEP 1: ERROR RESPONSE FORMAT**
Define a consistent error envelope:
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [{
      "field": "email",
      "reason": "INVALID_FORMAT",
      "message": "Must be a valid email address"
    }],
    "request_id": "req_abc123",
    "documentation_url": "https://api.example.com/docs/errors#VALIDATION_ERROR"
  }
}
```

**STEP 2: ERROR CODE TAXONOMY**
Create a hierarchical error code system:
- AUTH_* — Authentication errors (AUTH_EXPIRED, AUTH_INVALID, AUTH_MISSING)
- PERMISSION_* — Authorization errors
- VALIDATION_* — Input validation errors
- RESOURCE_* — Resource errors (NOT_FOUND, CONFLICT, GONE)
- RATE_* — Rate limiting errors
- INTERNAL_* — Server errors (never expose details)

**STEP 3: HTTP STATUS CODE MAPPING**
Map each error category to status codes:
- 400: VALIDATION_* errors
- 401: AUTH_* errors
- 403: PERMISSION_* errors
- 404: RESOURCE_NOT_FOUND
- 409: RESOURCE_CONFLICT
- 422: Semantic validation errors
- 429: RATE_LIMIT_EXCEEDED
- 500: INTERNAL_ERROR (generic)
- 503: SERVICE_UNAVAILABLE

**STEP 4: ERROR MIDDLEWARE IMPLEMENTATION**
Provide implementation patterns for:
- Global error handler
- Validation error aggregation
- Error logging with correlation IDs
- Error sanitization (strip stack traces in production)
- Retry-able vs non-retry-able error classification

**STEP 5: CLIENT-SIDE ERROR HANDLING GUIDE**
Create a guide for API consumers:
- How to parse error responses
- Retry strategies per error type
- Circuit breaker recommendations
- Error reporting and escalation

## INPUT
**API framework**: {framework}
**Error categories needed**: {categories}
**Current pain points**: {pain_points}

## OUTPUT FORMAT
Deliver the error handling system as a structured specification with code examples in the target framework, ready to implement.

## CONSTRAINTS
- Never expose stack traces or internal paths to clients
- Always include request_id for support debugging
- Error messages must be actionable (tell the user how to fix it)
- Support localization of error messages