API Response Format & Error Handling

Relevant source files

• README.md
• apps/documentation/bun.lock
• apps/documentation/package.json
• apps/documentation/src/assets/swagger.json
• apps/documentation/src/content/docs/specifications/backend/api-response-format.md
• apps/documentation/src/content/docs/specifications/backend/endpoints.md
• apps/documentation/src/content/docs/specifications/backend/error-handling.md
• apps/documentation/src/content/docs/specifications/frontend/api.md
• apps/documentation/src/content/docs/specifications/frontend/routing.md
• apps/documentation/src/tailwind.css

This document describes the standardized JSON response format and error handling conventions defined in the RealWorld API specification. All API endpoints follow consistent patterns for both successful responses and error conditions, ensuring predictable client integration.

For endpoint-specific details, see Endpoints Reference. For data model definitions, see Data Models & Schemas.

---

Response Format Overview

All API responses use JSON format and follow a consistent wrapping pattern. Success responses wrap the primary data object in a single root key that describes the resource type, while error responses use a standardized error structure.

Standard Response Wrapper Pattern

The API uses resource-specific wrapper keys to encapsulate response data:

Resource Type	Wrapper Key	Example Endpoint
User (authenticated)	user	POST /api/users/login
Profile	profile	GET /api/profiles/:username
Single Article	article	GET /api/articles/:slug
Multiple Articles	articles	GET /api/articles
Single Comment	comment	POST /api/articles/:slug/comments
Multiple Comments	comments	GET /api/articles/:slug/comments
Tags List	tags	GET /api/tags

Sources: apps/documentation/src/assets/swagger.json862-1005

Content-Type Requirements

All responses must include the correct content type header:

Content-Type: application/json; charset=utf-8

Implementations must ensure this header is set for all JSON responses to enable proper client-side parsing.

Sources: apps/documentation/src/content/docs/specifications/backend/api-response-format.md1-7

---

Success Response Structures

User Response (UserResponse)

Used for authentication and user profile operations. Returns the authenticated user object with JWT token.

HTTP Status: 200 OK (login/get/update) or 201 Created (registration)

Endpoints using this response:

• POST /api/users/login - Login
• POST /api/users - Registration (201)
• GET /api/user - Get current user
• PUT /api/user - Update user

Sources: apps/documentation/src/assets/swagger.json971-986 apps/documentation/src/content/docs/specifications/backend/api-response-format.md9-21

Profile Response (ProfileResponse)

Used for user profile views and follow operations.

HTTP Status: 200 OK

Endpoints using this response:

• GET /api/profiles/:username
• POST /api/profiles/:username/follow
• DELETE /api/profiles/:username/follow

Sources: apps/documentation/src/assets/swagger.json955-970 apps/documentation/src/content/docs/specifications/backend/api-response-format.md23-34

Single Article Response (SingleArticleResponse)

Returns a complete article with author profile and metadata.

HTTP Status: 200 OK (get/update/favorite) or 201 Created (create)

Endpoints using this response:

• GET /api/articles/:slug
• POST /api/articles (201)
• PUT /api/articles/:slug
• POST /api/articles/:slug/favorite
• DELETE /api/articles/:slug/favorite

Sources: apps/documentation/src/assets/swagger.json917-932 apps/documentation/src/content/docs/specifications/backend/api-response-format.md36-58

Multiple Articles Response (MultipleArticlesResponse)

Returns an array of articles with a total count. Note that list endpoints do not include the body field for performance optimization.

HTTP Status: 200 OK

Endpoints using this response:

• GET /api/articles (with optional tag, author, favorited, limit, offset query params)
• GET /api/articles/feed (with optional limit, offset query params)

Important: The body field is excluded from articles in list responses as of 2024-08-16 for performance reasons.

Sources: apps/documentation/src/assets/swagger.json933-954 apps/documentation/src/content/docs/specifications/backend/api-response-format.md60-104

Comment Responses

Single Comment (SingleCommentResponse):

Multiple Comments (MultipleCommentsResponse):

HTTP Status: 200 OK

Endpoints:

• POST /api/articles/:slug/comments - Create comment (SingleCommentResponse)
• GET /api/articles/:slug/comments - List comments (MultipleCommentsResponse)

Sources: apps/documentation/src/assets/swagger.json882-916 apps/documentation/src/content/docs/specifications/backend/api-response-format.md106-142

Tags Response (TagsResponse)

Returns a simple array of tag strings.

HTTP Status: 200 OK

Endpoint: GET /api/tags

Sources: apps/documentation/src/assets/swagger.json863-881 apps/documentation/src/content/docs/specifications/backend/api-response-format.md144-153

Empty Success Response (EmptyOkResponse)

Used for delete operations that complete successfully without returning data.

HTTP Status: 200 OK

Content: Empty response body ({} or no content)

Endpoints:

• DELETE /api/articles/:slug
• DELETE /api/articles/:slug/comments/:id

Sources: apps/documentation/src/assets/swagger.json987-990

---

Response Structure Mapping Diagram

Sources: apps/documentation/src/assets/swagger.json634-1005

---

Error Response Structure

All error responses follow the GenericErrorModel schema defined in the OpenAPI specification.

Error Response Format (GenericErrorModel)

The error structure consists of:

• Root errors object (required)
• body array containing error message strings (required)

Schema Definition: apps/documentation/src/assets/swagger.json843-860

Sources: apps/documentation/src/content/docs/specifications/backend/error-handling.md7-17

Validation Error Example

When request validation fails (HTTP 422), the response provides detailed error messages:

Multiple validation failures are accumulated in the body array.

Sources: apps/documentation/src/content/docs/specifications/backend/error-handling.md1-26

---

HTTP Status Codes

The API uses standard HTTP status codes to indicate the outcome of requests.

Success Status Codes

Status Code	Description	Usage
200 OK	Request succeeded	GET, PUT, DELETE operations
201 Created	Resource created successfully	POST /api/users (registration), POST /api/articles

Error Status Codes

Status Code	Description	When Used	Response Body
401 Unauthorized	Authentication required but not provided	Protected endpoints called without valid JWT token	Empty ({})
403 Forbidden	Request valid but user lacks permissions	User attempts action they're not authorized for	Empty or GenericErrorModel
404 Not Found	Requested resource doesn't exist	Invalid article slug, username, or comment ID	Empty or GenericErrorModel
422 Unprocessable Entity	Request validation failed	Invalid request body, missing required fields, validation errors	GenericErrorModel

Sources: apps/documentation/src/content/docs/specifications/backend/error-handling.md19-26 apps/documentation/src/assets/swagger.json51-628

Status Code Usage by Endpoint Type

Authentication Endpoints:

• POST /api/users/login → 200 (success), 401 (invalid credentials), 422 (validation error)
• POST /api/users → 201 (success), 422 (validation error)

Protected Endpoints (require authentication):

• Return 401 if Authorization: Token <jwt> header is missing or invalid
• Return 403 if user lacks permission (e.g., deleting another user's article)

Resource Endpoints:

• Return 404 if resource (article, profile, comment) not found
• Return 422 for validation errors on create/update operations

Sources: apps/documentation/src/assets/swagger.json42-632

---

Error Handling Flow Diagram

Sources: apps/documentation/src/assets/swagger.json41-632 apps/documentation/src/content/docs/specifications/backend/error-handling.md1-26

---

Response Schema Reference

Complete Response Type Mapping

The following table maps OpenAPI response definitions to their usage:

OpenAPI Response Name	HTTP Status	Wrapper Key(s)	Endpoints
UserResponse	200, 201	user	/api/users/login, /api/users, /api/user
ProfileResponse	200	profile	/api/profiles/:username, /api/profiles/:username/follow
SingleArticleResponse	200, 201	article	/api/articles/:slug, /api/articles, /api/articles/:slug/favorite
MultipleArticlesResponse	200	articles, articlesCount	/api/articles, /api/articles/feed
SingleCommentResponse	200	comment	/api/articles/:slug/comments (POST)
MultipleCommentsResponse	200	comments	/api/articles/:slug/comments (GET)
TagsResponse	200	tags	/api/tags
EmptyOkResponse	200	(empty)	DELETE operations
Unauthorized	401	(empty)	Protected endpoints without auth
GenericError	422, 404, 403	errors	Validation failures, not found

Sources: apps/documentation/src/assets/swagger.json862-1005

---

Implementation Guidelines

Content-Type Header

All implementations must set the response content type:

Content-Type: application/json; charset=utf-8

This ensures proper character encoding and JSON parsing on the client side.

Error Message Conventions

When returning validation errors (422), implementations should:

1. Accumulate all validation failures
2. Place human-readable messages in the errors.body array
3. Use consistent message formats (e.g., "can't be empty", "must be at least 8 characters")

Response Consistency

Implementations must adhere to:

• Correct wrapper key for each resource type
• Exact field names as defined in schemas (case-sensitive)
• ISO 8601 format for date fields (createdAt, updatedAt)
• Consistent use of null for empty optional fields

Authentication Error Handling

For protected endpoints (security: [{ Token: [] }] in OpenAPI spec):

• Missing or invalid Authorization header → 401 with empty body
• Valid token but insufficient permissions → 403
• Use consistent Authorization: Token <jwt> header format

Sources: apps/documentation/src/assets/swagger.json1133-1141 apps/documentation/src/content/docs/specifications/backend/api-response-format.md1-7

---

Response Validation Diagram

Sources: apps/documentation/src/assets/swagger.json634-1141