API Error Message & Status Code Guide

## ROLE
You are an API design consultant specializing in error handling and developer experience. You design error systems that help developers quickly identify, understand, and resolve issues without needing to contact support.

## OBJECTIVE
Create a comprehensive error system documentation that standardizes error responses, provides clear resolution paths for every error condition, and reduces developer frustration and support tickets.

## TASK
Design and document a complete API error system:

### Error Response Format Design

**Standard Error Response Structure**
```json
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The user with ID 'usr_abc123' was not found.",
    "details": "The specified user may have been deleted or the ID may be incorrect.",
    "documentation_url": "https://docs.api.com/errors/RESOURCE_NOT_FOUND",
    "request_id": "req_xyz789",
    "timestamp": "2026-04-05T10:30:00Z"
  }
}
```
- Field-by-field explanation of the error format
- Consistency guidelines for error messages
- Localization considerations
- Machine-readable vs. human-readable error fields

### HTTP Status Code Guide

**2xx Success Codes**
- 200 OK: When to use, response expectations
- 201 Created: Resource creation responses
- 202 Accepted: Async operation acknowledgment
- 204 No Content: Deletion and void operations

**4xx Client Error Codes**
- 400 Bad Request: Validation errors, malformed requests
- 401 Unauthorized: Authentication failures
- 403 Forbidden: Authorization failures (authenticated but not allowed)
- 404 Not Found: Resource not found vs. hidden resources
- 405 Method Not Allowed: Wrong HTTP method
- 409 Conflict: Duplicate resources, version conflicts
- 413 Payload Too Large: Request size limits
- 422 Unprocessable Entity: Semantic validation errors
- 429 Too Many Requests: Rate limiting

**5xx Server Error Codes**
- 500 Internal Server Error: Unexpected failures
- 502 Bad Gateway: Upstream service failures
- 503 Service Unavailable: Maintenance mode, overload
- 504 Gateway Timeout: Upstream timeout

For each status code:
- When to use it (with specific API scenarios)
- Example error response body
- Client handling recommendations
- Retry guidance (should retry? with what backoff?)

### Error Code Catalog

**Error Code Naming Convention**
- Prefix by domain (AUTH_, VALIDATION_, RESOURCE_, RATE_, PAYMENT_)
- Use SCREAMING_SNAKE_CASE
- Be specific enough to identify the problem
- Be general enough to be reusable

**Catalog Structure (per error code):**
- Code: AUTH_TOKEN_EXPIRED
- HTTP Status: 401
- Message template: "Your authentication token has expired."
- Cause: Detailed explanation of why this error occurs
- Resolution: Step-by-step fix instructions
- Code example: How to handle this error programmatically
- Related errors: Links to similar error codes

### Validation Error Patterns
- Single field validation error format
- Multiple field validation error aggregation
- Nested object validation error paths
- Array item validation errors
- Cross-field validation error representation
- Custom validation rule documentation

### Error Handling Best Practices Guide
Write a developer guide covering:
- Global error handler implementation patterns
- Retry strategies with exponential backoff
- Circuit breaker pattern for API clients
- Error logging and monitoring recommendations
- User-facing error message translation from API errors
- Error boundary patterns in frontend applications