NOTE
Designing an Error Model
Stable error taxonomy, machine-readable codes, retryability, user-facing messages, wrapping/context, cross-service mapping, and observability.
This is a historical learning note and may contain outdated or incomplete understanding.
1. Errors Are Part of the API
An error model should let callers decide what to do without parsing human text.
Separate:
- stable machine code/type;
- human/debug message;
- structured metadata;
- retryability or protocol status.
2. Taxonomy
Useful high-level classes include:
- invalid input;
- unauthenticated/forbidden;
- not found/conflict;
- rate limited/resource exhausted;
- dependency unavailable/timeout;
- internal invariant failure.
3. Preserve Cause and Context
Wrap errors with operation/context while preserving the underlying cause/type so logging and programmatic checks both work.
Do not expose internal stack traces or secrets to external callers.
4. Cross-Service Mapping
Map internal errors deliberately into HTTP/RPC contract errors. Avoid turning every downstream error into generic 500, and avoid leaking every storage error directly to clients.
5. Retryability
Make retry policy explicit. A timeout/unavailable error may be retryable; validation/permission errors are normally not.
Even for retryable errors, the operation must be idempotent or deduplicated.
6. Observability
Metrics should aggregate by stable error class/code, not raw message text. Logs/traces can retain detailed causes and request correlation IDs.