What is RFC 7807 (Problem Details for HTTP APIs)?

RFC 7807 defines a standardized JSON format for reporting errors from HTTP APIs. It provides machine-readable fields including type (URI reference), title (human-readable summary), status (HTTP code), detail (specific occurrence explanation), and instance (URI of the specific request).

When should an API return 422 Unprocessable Entity instead of 400 Bad Request?

Return 400 Bad Request when the server cannot parse the syntax of the request (e.g. malformed JSON or corrupted query strings). Return 422 Unprocessable Entity when the request syntax is valid JSON, but the contained fields fail semantic validation (e.g. an email field missing an @ symbol or an age field containing a negative number).

When should a REST API return 204 No Content?

Return 204 No Content when an action succeeds and no additional information or updated representation needs to be returned to the client, such as a successful DELETE operation.

Are my API schema designs or queries stored on remote servers?

No. All status calculations, decision logic, and JSON payload generations execute 100% locally inside your web browser using client-side JavaScript. No data is logged or uploaded.

REST API Design Assistant

REST API Status Code Decision Assistant

Select the exact HTTP status code your REST API endpoint should return. Features an interactive decision tree, RFC 9110 guidelines, and RFC 7807 JSON error payload generation.

Step 1: What is the outcome of the API request?

200 OK RFC 9110

Recommended API Implementation

Standard Successful Response

RFC 7807 Standard Error / Response Payload:

1. The Importance of Semantic HTTP Status Codes in REST APIs

Representational State Transfer (REST) APIs rely on standard HTTP protocol methods (GET, POST, PUT, PATCH, DELETE) and semantic status codes to communicate client-server outcomes. Returning 200 OK for an unhandled database failure with {"error": true} in the JSON body is considered an anti-pattern because it disrupts API gateways, caching layers, and client error handling.

Proper status code selection allows client libraries (such as Axios or Fetch) to trigger error interceptors, re-authenticate users on 401, and apply exponential backoff on 429 without manually inspecting the response body.

2. Standard REST API Status Code Reference

HTTP Status	Canonical Title	Standard REST Use Case	RFC Reference
200	OK	Successful read or update operations (GET, PUT, PATCH)	RFC 9110 §15.3.1
201	Created	New resource successfully created (POST); returns Location header	RFC 9110 §15.3.2
204	No Content	Successful action with empty response body (DELETE)	RFC 9110 §15.3.5
400	Bad Request	Malformed request syntax or unparseable JSON stream	RFC 9110 §15.5.1
401	Unauthorized	Missing or expired authentication credentials (Bearer token)	RFC 9110 §15.5.2
403	Forbidden	Authenticated identity lacks permission to access resource	RFC 9110 §15.5.4
404	Not Found	Target resource URI does not exist	RFC 9110 §15.5.5
409	Conflict	Duplicate entry violating a unique database constraint	RFC 9110 §15.5.10
422	Unprocessable Entity	Valid JSON syntax that fails semantic business validation rules	RFC 9110 §15.5.21
429	Too Many Requests	Client exceeded configured rate limit quotas; send Retry-After	RFC 6585 §4
500	Internal Server Error	Generic unhandled application exception or database crash	RFC 9110 §15.6.1

3. Understanding RFC 7807: Problem Details for HTTP APIs

Modern cloud architecture increasingly adopts RFC 7807 (Problem Details) to eliminate proprietary error formats across microservices. Instead of returning disparate payloads like {"err": "message"}, RFC 7807 specifies a standard schema:

type: A URI identifier that categorizes the problem type.
title: A short, human-readable summary of the problem type (should not change from occurrence to occurrence).
status: The HTTP status code generated by the origin server.
detail: A human-readable explanation specific to this occurrence of the problem.
instance: A URI reference identifying the specific occurrence of the problem (e.g., request ID or endpoint).

4. Client-Side Execution & Privacy Guarantee

All status code determinations, decision tree traversals, and RFC 7807 JSON generations run 100% locally inside your browser session using JavaScript. No API endpoint schemas, internal routing definitions, or custom data structures are uploaded or stored on remote servers.

5. Frequently Asked Questions

Why should I use 422 instead of 400 for form validation errors?

A 400 Bad Request indicates that the web server or parser could not understand the request due to syntax errors (such as invalid JSON formatting). When the JSON is syntactically valid but specific fields fail validation (e.g., a password is too short or an email already exists), 422 Unprocessable Entity informs the client that the syntax was understood, but the instructions could not be processed.

When should I return 204 No Content vs 200 OK?

Return 204 No Content when an action is complete and the client does not need to parse any payload body (such as a successful DELETE or a background preference update). Return 200 OK if the response returns an updated resource representation.

Should API errors include sensitive stack traces?

Never expose internal stack traces, database schema names, or raw SQL queries in public API error responses. Use RFC 7807 to return high-level explanations in the detail field, and log the detailed stack trace internally with an instance ID for correlation.