Error response format in Rest API - Deep Dive

Overview - Error response format

What is it?

An error response format is a standard way for a REST API to tell clients that something went wrong. It usually includes information like an error code, a message explaining the problem, and sometimes extra details to help fix it. This format helps clients understand and handle errors properly. Without it, clients would struggle to know why their requests failed.

Why it matters

Without a clear error response format, users and developers would get confused when something breaks. They might see only vague messages or no explanation at all, making it hard to fix issues or improve the system. A good error format improves communication between the server and client, making apps more reliable and user-friendly.

Where it fits

Before learning error response formats, you should understand basic REST API concepts like requests, responses, and HTTP status codes. After this, you can learn about advanced API design, error handling best practices, and client-side error processing.

Mental Model

Core Idea

An error response format is a clear, consistent message from the server that explains what went wrong and how the client can respond.

Think of it like...

It's like a traffic light for drivers: green means go, red means stop, and a flashing red or a sign explains why you must stop and what to do next.

┌─────────────────────────────┐
│        HTTP Response        │
├─────────────┬───────────────┤
│ Status Code │ 4xx or 5xx    │
├─────────────┼───────────────┤
│ Body        │ {
│             │   "error": {
│             │     "code": "string",
│             │     "message": "string",
│             │     "details": "optional"
│             │   }
│             │ }             │
└─────────────┴───────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding HTTP Status Codes

Concept: Learn what HTTP status codes are and how they signal success or failure.

HTTP status codes are numbers sent by the server to tell the client if a request worked or not. Codes starting with 2 (like 200) mean success. Codes starting with 4 (like 404) mean the client made a mistake. Codes starting with 5 (like 500) mean the server had a problem.

Result

You can tell if a request succeeded or failed just by looking at the status code.

Knowing status codes is the first step to understanding how errors are communicated in APIs.

2

Foundation

What is an Error Response Format?

Concept: Introduce the idea of a structured message explaining errors beyond just status codes.

An error response format is a way to send extra information about an error. Instead of just a number, the server sends a message and sometimes a code or details. This helps the client understand what went wrong and how to fix it.

Result

Clients get clear, useful information about errors, not just a number.

Status codes alone are not enough; a message helps humans and programs handle errors better.

3

Intermediate

Common Fields in Error Responses

🤔Before reading on: do you think error responses should include only a message, or also a code and details? Commit to your answer.

Concept: Learn the typical parts of an error response: code, message, and optional details.

Most error responses have: - code: a short string or number identifying the error type - message: a human-readable explanation - details: extra info like which field caused the error or suggestions Example: { "error": { "code": "INVALID_INPUT", "message": "The 'email' field is missing.", "details": "Please provide a valid email address." } }

Result

You understand what information to include to help clients fix errors.

Including structured fields makes error handling easier and more consistent.

4

Intermediate

Using Standard vs Custom Error Codes

🤔Before reading on: do you think using only HTTP status codes is enough, or are custom error codes helpful? Commit to your answer.

Concept: Explore why APIs use both HTTP status codes and their own error codes.

HTTP status codes are broad and sometimes vague. Custom error codes give precise reasons for failure. For example, 400 means bad request, but a custom code like 'MISSING_PARAMETER' tells exactly what is wrong. Combining both helps clients react correctly.

Result

You can design error responses that are both standard and specific.

Custom codes add clarity and allow clients to handle errors programmatically.

5

Intermediate

Error Response Formats in Popular APIs

Concept: See real examples from well-known APIs to understand common patterns.

Google APIs use: { "error": { "code": 400, "message": "Invalid value", "errors": [ {"message": "Invalid value", "domain": "global", "reason": "invalid"} ] } } GitHub API uses: { "message": "Not Found", "documentation_url": "https://docs.github.com/rest" } These examples show different ways to provide error info.

Result

You recognize common fields and structures in real-world APIs.

Studying popular APIs helps you design your own error formats that are familiar to developers.

6

Advanced

Designing Extensible Error Formats

🤔Before reading on: do you think error formats should be fixed or allow adding new fields? Commit to your answer.

Concept: Learn how to design error responses that can grow without breaking clients.

Good error formats use a main 'error' object with known fields and allow extra fields for future needs. For example, adding a 'timestamp' or 'traceId' helps debugging but doesn't break old clients. Using JSON objects instead of plain strings makes this possible.

Result

Your error responses can evolve as your API grows, keeping backward compatibility.

Extensibility prevents costly changes and improves long-term API stability.

7

Expert

Handling Errors in Distributed Systems

🤔Before reading on: do you think error responses in distributed systems need special handling? Commit to your answer.

Concept: Understand challenges and solutions for error formats when APIs call other APIs or services.

In distributed systems, errors can come from multiple layers. Wrapping errors with context, using unique IDs, and propagating trace information helps track root causes. Formats may include nested errors or links to logs. This complexity requires careful design to avoid confusing clients.

Result

You can design error responses that help diagnose problems across many services.

Knowing how to handle multi-layer errors is key for reliable, maintainable large systems.

Under the Hood

When a REST API detects a problem, it sets an HTTP status code indicating failure and sends a response body in a structured format, usually JSON. The server software serializes an error object with fields like code and message. Clients parse this JSON to understand the error. This process relies on HTTP standards for status codes and JSON for data exchange.

Why designed this way?

HTTP status codes provide a universal, simple way to signal success or failure, but they are limited in detail. JSON is widely supported and easy to parse, making it ideal for structured error messages. This design balances standardization with flexibility, allowing APIs to communicate rich error information while remaining compatible with many clients.

┌───────────────┐
│ Client sends  │
│ HTTP request  │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Server receives│
│ request       │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Server detects │
│ error         │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Server sends  │
│ HTTP response │
│ with status   │
│ code + JSON   │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Client parses │
│ error format  │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think HTTP status codes alone are enough to fully explain API errors? Commit to yes or no.

Common Belief: HTTP status codes like 400 or 500 are enough to tell clients what went wrong.

Reality: Status codes give a broad category but lack details needed to fix the problem, so error response bodies are necessary.

Why it matters: Relying only on status codes leaves clients guessing and leads to poor user experience and harder debugging.

Quick: Do you think error messages should be vague to avoid exposing server details? Commit to yes or no.

Common Belief: Error messages should be vague to protect server security and avoid confusing users.

Reality: Clear, specific error messages help clients fix issues faster without exposing sensitive internal info if designed carefully.

Why it matters: Vague errors frustrate developers and users, increasing support costs and slowing development.

Quick: Do you think all APIs use the same error response format? Commit to yes or no.

Common Belief: All REST APIs follow a single standard error response format.

Reality: There is no universal standard; different APIs use different formats, though many follow similar patterns.

Why it matters: Assuming one format fits all can cause integration bugs and confusion when working with multiple APIs.

Quick: Do you think error responses should always use HTTP 200 status code with error info inside? Commit to yes or no.

Common Belief: It's okay to always return HTTP 200 and put error details inside the response body.

Reality: Using proper HTTP error status codes is important for clients and intermediaries to detect errors correctly.

Why it matters: Ignoring status codes breaks caching, monitoring, and client error handling, causing hidden failures.

Expert Zone

1

Some APIs use error sub-codes to allow clients to handle errors differently even if the HTTP status is the same.

2

Including a unique error ID or trace ID in responses helps correlate client errors with server logs for debugging.

3

Error response formats can include links to documentation or support resources to guide developers in fixing issues.

When NOT to use

In very simple or internal APIs, detailed error formats may be overkill; simple status codes and messages might suffice. For streaming or binary protocols, different error signaling methods are needed.

Production Patterns

In production, APIs often log errors with full context and return sanitized error responses. They use layered error handling to catch unexpected failures and return consistent formats. Monitoring systems track error codes and rates to alert teams.

Connections

HTTP Status Codes

Builds-on

Understanding error response formats deepens your knowledge of HTTP status codes by showing how they work together to communicate problems.

User Experience Design

Builds-on

Clear error messages improve user experience by guiding users to fix problems, reducing frustration and support calls.

Human Communication Theory

Same pattern

Error response formats mirror how humans use clear, structured messages to avoid misunderstandings in communication.

Common Pitfalls

#1 Returning only HTTP status codes without a message body.

Wrong approach:

HTTP/1.1 400 Bad Request

Correct approach:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":{"code":"BAD_REQUEST","message":"Missing required field 'name'."}}

Root cause:

Believing status codes alone are enough for clients to understand errors.

#2 Using HTTP 200 status code for error responses.

Wrong approach:

HTTP/1.1 200 OK
Content-Type: application/json

{"error":{"code":"NOT_FOUND","message":"User not found."}}

Correct approach:

HTTP/1.1 404 Not Found
Content-Type: application/json

{"error":{"code":"NOT_FOUND","message":"User not found."}}

Root cause:

Misunderstanding the role of HTTP status codes in signaling success or failure.

#3 Including sensitive internal error details in the response.

Wrong approach:

{"error":{"code":"DB_ERROR","message":"Database connection failed: password incorrect."}}

Correct approach:

{"error":{"code":"DB_ERROR","message":"Internal server error. Please try again later."}}

Root cause:

Not considering security and privacy when designing error messages.

Key Takeaways

Error response formats are structured messages that explain why an API request failed, beyond just HTTP status codes.

Combining HTTP status codes with clear error codes and messages helps clients understand and fix problems effectively.

Designing extensible and consistent error formats improves API usability and long-term maintenance.

Avoid vague messages and improper use of status codes to prevent confusion and hidden errors.

Advanced error handling in distributed systems requires adding context and traceability to error responses.