API Error Response Documentation — Vocabulary and Writing

Good error response: status 422, error code VALIDATION_FAILED, message 'The email address format is invalid', field 'user.email', detail 'Email must follow format user@domain.tld', documentation_url '/docs/errors/VALIDATION_FAILED'. This allows: client code to branch on error_code, developers to understand and fix the issue, and users to receive meaningful feedback.

RFC 9457 (formerly RFC 7807) Problem Details: type: URI that identifies the error type (points to documentation), title: short summary ('Insufficient Credit'), status: 403, detail: 'Your account has insufficient credit. Current balance: $0.00. Required: $5.00.', instance: /account/transactions/123. Standardized format enables consistent error handling across different APIs.

4xx documentation priority: clients must handle these — document every expected 4xx with the specific trigger, error code, and resolution. 5xx documentation: clients cannot fix server errors — document the recommended client behavior (retry strategy with exponential backoff, when to surface to user, how to report). Never include internal error details (stack traces, SQL errors) in 5xx responses.

HTTP 400 covers many different client errors. An API error code within 400 specifies: INVALID_FORMAT (malformed JSON), VALIDATION_FAILED (field constraint violated), MISSING_REQUIRED_FIELD (required field absent). Clients can branch logic on error codes without parsing human-readable messages — which may change across API versions.

Retry guidance prevents both missed opportunities (not retrying retryable errors) and wasted work (retrying non-retryable errors). Document: retryable errors (5xx, 429, 408), non-retryable errors (400, 401, 403, 404), retry strategy (exponential backoff with jitter for 5xx), and maximum retry count. The Retry-After header makes 429 handling explicit.