API Error Response Standardizer

Prompt Template

You are an API design expert who creates developer-friendly error experiences. Design a standardized error response system.

API type: {{api_type: REST/GraphQL}}
Stack: {{stack}}
Current error format: {{current: inconsistent/basic/none}}
API consumers: {{consumers: web frontend/mobile/third-party}}
Documentation: {{docs: OpenAPI/none/custom}}

## Error Response Format
```
error:
  code: RESOURCE_NOT_FOUND
  message: The requested user could not be found.
  details: []
  request_id: req_abc123
  documentation_url: https://api.example.com/docs/errors#RESOURCE_NOT_FOUND
```

## Error Catalog
| Error Code | HTTP Status | Message Template | When to Use |
| VALIDATION_ERROR | 400 | Field {field} {reason} | Invalid input |
| UNAUTHORIZED | 401 | Authentication required | Missing/invalid token |
| FORBIDDEN | 403 | Insufficient permissions | Valid token, wrong role |
| NOT_FOUND | 404 | {resource} not found | Resource does not exist |
| CONFLICT | 409 | {resource} already exists | Duplicate creation |
| RATE_LIMITED | 429 | Rate limit exceeded, retry after {seconds} | Too many requests |
| INTERNAL_ERROR | 500 | An unexpected error occurred | Unhandled exception |

## Implementation
```{{language}}
// Error class hierarchy
// Error middleware/handler
// Helper functions for common errors
```

## Validation Error Format
```
error:
  code: VALIDATION_ERROR
  message: Request validation failed.
  details:
    - field: email
      reason: Must be a valid email address
      value: not-an-email
```

## Client Integration Guide
- How frontend should handle each error code
- Retry strategy per error type
- User-facing message mapping

## Security Considerations
- Never expose stack traces in production
- Do not reveal whether a resource exists in auth errors
- Rate limit information disclosure policy

Tips

• Consistent error formats save frontend developers hours of special-case handling
• Include request_id in every error response for debugging - without it production errors are needles in haystacks
• The security considerations section prevents information leakage that attackers exploit
• Document every error code publicly so API consumers can handle them programmatically