API Error Handling Framework

API error handling fails when errors are designed for the API author's convenience rather than the consumer's ability to handle them. An error response of {"message": "Something went wrong"} tells the consumer exactly nothing useful — they don't know what went wrong, whether retrying will help, or how to fix their request. Error responses must be designed as a contract: consumers write code that handles specific error conditions, and that code can only be written if error conditions are documented, stable, and machine-readable.

The API Error Handling Framework defines the error response schema, builds the error code catalog, structures field-level validation errors, and distinguishes retryable from non-retryable errors.