What is RFC 7807 and why should I use it for API errors?

RFC 7807 (updated by RFC 9457) defines Problem Details, a standard JSON format for HTTP API error responses. It specifies fields like type (URI identifying the error), title (human-readable summary), status (HTTP status code), detail (specific explanation), and instance (URI for this occurrence). Using it means all your errors follow a consistent, documented schema that client libraries can handle generically. It is recommended by API design guides from Google, Microsoft, Stripe, and the IETF.

How should I report field-level validation errors in API responses?

Add an errors array to the Problem Details response, where each entry includes the field name (using dot notation for nested fields like address.zip), a machine-readable code (REQUIRED, INVALID_FORMAT, TOO_SHORT), a human-readable message, and optionally the rejected value. Set the HTTP status to 422 Unprocessable Entity. This gives clients enough information to display inline validation messages next to form fields and enough specificity for programmatic error handling.

Should error messages be localized on the server or the client?

Both approaches work. Server-side localization using the Accept-Language header is simpler for web clients but requires maintaining translations on the server. Client-side localization using stable error codes and parameter objects scales better for mobile apps and SPAs that bundle their own translation files. The best approach is to always include a machine-readable error_code that never changes, and provide a human-readable detail field that the server can optionally localize. Clients that need custom translations ignore detail and use error_code to look up their own messages.

What can I learn from Stripe and GitHub API error designs?

Stripe includes a doc_url linking directly to error documentation, a param field indicating which input caused the error, and nested error codes (type, code, decline_code) for progressively specific handling. GitHub includes a resource field identifying which model failed and a documentation_url. Both patterns are worth adopting: always include a link to error documentation and identify which specific input or resource caused the failure.

How do I design errors that client SDKs can easily wrap in typed exceptions?

Use consistent field names across all error responses: status, error_code, detail, and errors (for validation). This lets SDK generators create a single ApiError class with properties for each field and helper methods like isValidation(), isAuth(), and getFieldError(field). Include the HTTP status in the body so SDK code does not need to track it separately. Use stable string error codes rather than numeric codes so they are self-documenting in client code.

Designing Error Responses for Developer Experience