When an API returns a 401, 422, or 429 and the docs say nothing about error responses, developers have no way to write correct error handling — they cargo-cult whatever they saw in a Stack Overflow answer. Libraries that throw custom error classes but never document them force consumers to catch generic Error and inspect message strings, a fragile pattern that breaks across versions. Every undocumented error is a latent incident: the integrator doesn't know the error is possible, doesn't handle it, and a user sees an unhandled exception. iso-25010:2011 analysability covers this: a system where all failure modes are documented is fundamentally more maintainable than one where they are discovered at runtime.
High because undocumented error codes mean consumer applications cannot implement correct error handling, turning every production failure into a novel debugging session rather than a handled case.
Add an Errors section to your API reference with every status code, its cause, and how to resolve it:
## Errors
| Status | Code | Cause | Resolution |
|--------|------|-------|------------|
| 400 | invalid_request | Body failed validation | Check required fields and types |
| 401 | unauthorized | API key missing or invalid | Verify your API key |
| 404 | not_found | Resource does not exist | Check the resource ID |
| 429 | rate_limited | Too many requests | Retry after the Retry-After header value |
| 500 | internal_error | Server error | Contact support with the request ID |
For libraries, document every custom error class with the conditions that trigger it. Enumerate the complete error set — partial error docs give a false sense of completeness.
ID: developer-documentation.api-reference.error-docs
Severity: high
What to look for: Check whether the documentation lists error codes, error types, or error responses that the API or library can return. For REST APIs, check for HTTP status code documentation (400, 401, 403, 404, 422, 500). For libraries, check for custom error classes or error types. Verify that each error includes a description of what causes it and how to resolve it. Count every distinct error code returned by the API and enumerate which are documented. Report: X of Y error codes are cataloged.
Pass criteria: Documentation lists all error codes or types the project can return, with causes and resolution guidance. For APIs: HTTP status codes with example error response bodies. For libraries: custom error types or thrown exceptions with descriptions. At least 1 implementation must be confirmed.
Fail criteria: No error documentation exists, or errors are mentioned without explanation of causes or resolution. Common pattern: API returns { "error": "..." } but docs never describe what errors are possible.
Skip (N/A) when: The project cannot produce user-facing errors (purely decorative UI component, static content generator with no failure modes).
Cross-reference: The code-examples check verifies that error handling is demonstrated in code samples, complementing this error documentation.
Detail on fail: Example: "API returns 5 different error status codes (400, 401, 403, 404, 500) but documentation does not list any error responses" or "Library throws InvalidConfigError and AuthenticationError but neither is documented"
Remediation: Add an errors section to your API reference:
## Errors
| Status | Code | Description | Resolution |
|--------|------|-------------|------------|
| 400 | invalid_request | Request body failed validation | Check required fields and types |
| 401 | unauthorized | API key is missing or invalid | Verify your API key |
| 404 | not_found | Resource does not exist | Check the resource ID |
| 429 | rate_limited | Too many requests | Wait and retry after Retry-After header |