Error Taxonomy
An error taxonomy classifies failures by cause, retryability, and ownership, so clients, operators, and dashboards respond consistently instead of guessing.
Definition
An error taxonomy is a structured classification of failure types, with stable codes and semantics that determine handling, reporting, and ownership.
Context and scope
Used in APIs, SDKs, and platforms where many services and clients must agree on which failures are retryable, permanent, or defects.
Common misconceptions
- HTTP status codes are a complete error taxonomy
- Every error should receive a unique code
- Internal error details should be returned so clients can debug
Anti-patterns
- Returning 500 for validation failures
- Changing the meaning of an error code without versioning
- Leaking stack traces or dependency names in public responses
Related concepts
Related examples
Authoritative source
Why classify errors
An error taxonomy gives failures stable names and meanings. Without one, every caller invents its own interpretation: retry the 500, ignore the 400, page on the 409. The taxonomy answers three questions consistently: what kind of failure occurred, whether retrying can help, and who owns the resolution. It turns error handling from guesswork into a contract shared by services, clients, and operators.
Useful dimensions
Classify by cause: validation, authentication, authorization, not found, conflict, rate limit, dependency failure, timeout, and internal defect. Classify by retryability: safe to retry, retry only after a delay, retry with a new idempotency key, never retry. Classify by blame boundary: caller error, service error, or dependency error. Add a stable machine-readable code, a human-readable message, and optional structured details. For example, a payment decline and a payment provider outage are both failures, but only one is retryable.
Design rules
Use transport status codes for coarse semantics and domain codes for precision. Keep codes stable; changing meaning breaks clients silently. Do not expose stack traces, SQL, or internal hostnames. Include a correlation identifier for support, never secrets or personal data. Document which codes are retryable and what backoff to use. Version the taxonomy when semantics must change.
Handling and observability
Clients should branch on codes, not message text. Gateways can map dependency failures into consistent codes. Dashboards should group by category and owner so a spike in validation errors is not confused with an outage. Alert on categories that indicate service defects, and use the same taxonomy in logs and traces.
Limits
A taxonomy cannot fix ambiguous failures. Timeouts may hide a successful write, which is why idempotency matters. Compared to a loose collection of messages, a taxonomy adds upfront design cost but reduces integration bugs and speeds diagnosis.