◆Error Codes Wiki

API Error Responses — Standard Error Format and HTTP Status Code Selection

Informational4xx client error

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

  1. 1Use RFC 7807 format: {type, title, status, detail, instance} for error responses
  2. 2Map validation errors to 400, authentication to 401, authorization to 403
  3. 3Include a machine-readable error code (e.g., 'INSUFFICIENT_FUNDS') alongside the message
  4. 4Return a list of specific field errors for validation failures
  5. 5Log request IDs and include them in error responses for debugging
  6. 6Document all possible error codes and their meanings in your API documentation

Tags

api-errorserror-responserfc-7807status-codesrest-api

Related Items

http-400-bad-requesthttp-422-unprocessable-entity-guidehttp-500-internal-server-error

More in 4xx Client Error

http-400-bad-requestHTTP 400 Bad Request — What It Means & How to Fix It
Error
http-401-unauthorizedHTTP 401 Unauthorized — What It Means & How to Fix It
Error
http-402-payment-requiredHTTP 402 Payment Required — What It Means & How to Fix It
Error
http-403-forbiddenHTTP 403 Forbidden — What It Means & How to Fix It
Error
http-404-not-foundHTTP 404 Not Found — What It Means & How to Fix It
Error
http-405-method-not-allowedHTTP 405 Method Not Allowed — What It Means & How to Fix It
Error

Frequently Asked Questions

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).