API Error Handling & Response Standard

You are a platform engineer responsible for establishing API standards across an engineering organization. Create a complete error handling and response specification for the following API platform.

Platform Context:
API Style: [REST/GRAPHQL/GRPC/MIXED]
Consumer Types: [INTERNAL DEVELOPERS/THIRD-PARTY DEVELOPERS/BOTH]
API Count: [NUMBER OF APIS OR MICROSERVICES]
Current Pain Points: [INCONSISTENT ERRORS/POOR DEBUGGING/MISSING CONTEXT/SECURITY LEAKS]
Localization Needs: [ENGLISH ONLY/MULTI-LANGUAGE]
Compliance Requirements: [PCI/HIPAA/GDPR/NONE]

Section 1 - Error Taxonomy and Classification:
Define the error category hierarchy starting with broad categories including validation errors, authentication errors, authorization errors, resource errors, conflict errors, rate limit errors, and server errors. Create subcategories within each major category with specific machine-readable error codes following a consistent naming pattern such as VALIDATION_REQUIRED_FIELD or AUTH_TOKEN_EXPIRED. Map each error code to the appropriate HTTP status code with detailed rationale for borderline cases like 400 versus 422 for validation errors. Define the severity levels for each error category that drive monitoring, alerting, and incident response behavior. Create the error code registry document that serves as the authoritative reference for all error codes across the platform. Specify the error code governance process for requesting new error codes and retiring obsolete ones.

Section 2 - Response Format Design:
Design the standard error response envelope with fields for error code, human-readable message, detailed description, request ID for support correlation, documentation link, and timestamp. Create the field-level validation error format that maps specific validation failures to their corresponding request fields with path notation for nested objects. Define the multiple error response format for endpoints that can return several errors simultaneously such as bulk operations. Specify the error response format for different API styles including REST JSON errors, GraphQL error extensions, and gRPC status details. Design the error metadata extension mechanism that allows specific APIs to include additional context without breaking the standard format. Create the success response envelope that maintains consistency with error responses using a unified envelope pattern or justify separate formats.

Section 3 - Error Message Authoring Guidelines:
Establish the message writing guidelines that produce clear, actionable error messages specifying what went wrong and how to fix it. Define the multi-audience message strategy with developer-facing technical messages and end-user-facing friendly messages in the same response. Create the message template system that generates consistent messages for common error patterns while avoiding information leakage about internal implementation. Specify the localization architecture for translating error messages including how message templates are managed, how locale is determined from the request, and fallback behavior. Define the PII and security review process for error messages ensuring that internal paths, database details, stack traces, and user data are never exposed to API consumers. Create the error message style guide with concrete examples of good and bad error messages for each error category.

Section 4 - Client Guidance and Recovery:
Design the retry guidance system that includes Retry-After headers, retryable error indicators, and suggested backoff strategies in error responses. Create the error documentation structure that provides detailed troubleshooting guides for each error code including common causes, step-by-step resolution, and code examples. Define the error context enrichment that provides enough information for clients to programmatically handle errors including which field failed, what values are acceptable, and what permissions are required. Specify the partial success response format for operations that partially complete including which items succeeded, which failed, and whether the operation can be resumed. Design the degraded mode communication that informs clients when the API is operating with reduced functionality and what features are unavailable. Create the error rate limit interaction design that clearly communicates when errors are caused by rate limiting versus actual failures.

Section 5 - Server-Side Error Processing:
Design the error handling middleware architecture that catches exceptions at different layers and transforms them into standard error responses. Define the error logging strategy that captures full error context including stack traces, request details, and user context for debugging without exposing this to the client. Create the error correlation system using request IDs that allow support teams to trace a client-reported error to the specific server logs and distributed trace. Specify the sensitive error masking rules that replace internal error details with generic messages for specific error categories while preserving debugging information in internal logs. Design the error aggregation pipeline that groups related errors, detects error spikes, and generates alerts based on error rate thresholds. Define the unhandled error safety net that catches unexpected exceptions and returns a well-formatted 500 response without leaking internal state.

Section 6 - Testing, Monitoring, and Compliance:
Create the error response testing strategy including contract tests that validate response format, integration tests that verify error scenarios, and fuzz tests that ensure the API never returns unformatted errors. Design the error monitoring dashboard that tracks error rates by code, endpoint, and consumer with time-series visualization and anomaly detection. Specify the error SLA metrics including acceptable error rates by category, mean time to detect error spikes, and mean time to resolve. Define the compliance audit trail for errors in regulated domains including what error information is logged, how long it is retained, and who can access error logs. Create the error standard adoption checklist for new APIs being onboarded to the platform. Document the quarterly error review process that analyzes error patterns, identifies top consumer pain points, and drives API improvement priorities.