The Importance of Rich Error Messages
Summary: Errors are part of every system. Rich, structured error messages allow humans and machines to understand failures, diagnose problems, automate recovery, and improve interoperability.
Context
Many platforms invest significant effort in defining APIs and data models while treating error handling as an afterthought.
A well-designed error response should communicate:
- What happened
- Why it happened
- Which component detected the problem
- Whether the fault is temporary or permanent
- What corrective action can be taken
The Cost of Poor Error Handling
Increased Support Costs
Every missing detail increases diagnosis time.
Reduced Automation
Structured errors enable automated decision making.
Interoperability Challenges
Without a common semantic error model, each interface behaves differently.
What Makes an Error Rich?
Error Identity
- ValidationError
- AuthenticationFailed
- ResourceNotFound
- AccessDenied
Human Readable Description
Provide a concise explanation for operators and users.
Machine Readable Classification
- Client Error
- Server Error
- Validation Error
- Security Error
Structured Detail
Maintain machine-readable diagnostic information.
Correlation Information
- Request ID
- Correlation ID
- Workflow ID
- Transaction ID
SOAP Faults and RFC 7807 Solve the Same Problem
SOAP Fault
- Code
- Subcode
- Reason
- Detail
RFC 7807 Problem Details
- type
- title
- status
- detail
- instance
Canonical Error Models
A canonical fault model can be projected into:
- SOAP Fault
- RFC 7807 JSON
- Event Streams
- Audit Records
- Monitoring Systems
Design Philosophy
Success responses describe expected behaviour.
Error responses describe unexpected behaviour.
Rich error messages are not merely diagnostics.
They are part of the platform's contract.
