API Error Responses — Standard Error Format and HTTP Status Code Selection
About API Error Responses
Guide to designing and handling API error responses including proper HTTP status code selection, error response body formats, and common API error patterns. This guide covers everything you need to know about this topic, including common causes, step-by-step solutions, and answers to frequently asked questions.
Here are the key things to understand: Well-designed APIs use standard HTTP status codes combined with structured error response bodies. RFC 7807 (Problem Details for HTTP APIs) defines a standard JSON error format with type, title, status, detail, instance. Common pattern: 400 for validation errors, 401 for auth, 403 for permissions, 404 for not found, 422 for semantic errors. Error responses should include machine-readable error codes and human-readable messages. Avoid returning 200 OK with an error in the body — this breaks HTTP semantics. Understanding these fundamentals will help you diagnose and resolve this issue more effectively.
The most common reasons this occurs include: API returning generic 500 for all errors instead of specific status codes. Missing error details in response body making debugging difficult. Inconsistent error format across different API endpoints. Using 200 OK with error field instead of proper HTTP error codes. Identifying the root cause is the first step toward finding the right solution.
To resolve this, follow these recommended steps: Use RFC 7807 format: {type, title, status, detail, instance} for error responses. Map validation errors to 400, authentication to 401, authorization to 403. Include a machine-readable error code (e.g., 'INSUFFICIENT_FUNDS') alongside the message. Return a list of specific field errors for validation failures. Log request IDs and include them in error responses for debugging. Document all possible error codes and their meanings in your API documentation. If these steps do not resolve the issue, consider consulting additional resources or a qualified professional.
This article is part of our HTTP Status Codes collection on Error Codes Wiki. We provide comprehensive, up-to-date information to help you find solutions quickly.
Quick Answer
Should I use 400 or 422 for validation errors?
Use 400 for malformed requests (bad JSON, wrong content-type) and 422 for syntactically correct but semantically invalid data (email already taken, invalid date range).
Overview
Guide to designing and handling API error responses including proper HTTP status code selection, error response body formats, and common API error patterns.
Key Details
- Well-designed APIs use standard HTTP status codes combined with structured error response bodies
- RFC 7807 (Problem Details for HTTP APIs) defines a standard JSON error format with type, title, status, detail, instance
- Common pattern: 400 for validation errors, 401 for auth, 403 for permissions, 404 for not found, 422 for semantic errors
- Error responses should include machine-readable error codes and human-readable messages
- Avoid returning 200 OK with an error in the body — this breaks HTTP semantics
Common Causes
- API returning generic 500 for all errors instead of specific status codes
- Missing error details in response body making debugging difficult
- Inconsistent error format across different API endpoints
- Using 200 OK with error field instead of proper HTTP error codes
Steps
- 1Use RFC 7807 format: {type, title, status, detail, instance} for error responses
- 2Map validation errors to 400, authentication to 401, authorization to 403
- 3Include a machine-readable error code (e.g., 'INSUFFICIENT_FUNDS') alongside the message
- 4Return a list of specific field errors for validation failures
- 5Log request IDs and include them in error responses for debugging
- 6Document all possible error codes and their meanings in your API documentation