Why error handling differs from REST in GraphQL - Why It Works This Way

Overview - Why error handling differs from REST

What is it?

Error handling in GraphQL is different from REST because GraphQL returns errors alongside data in a single response, rather than using HTTP status codes alone. This means clients get partial data even if some parts fail. REST typically uses separate HTTP status codes to indicate success or failure of the entire request.

Why it matters

Without understanding these differences, developers might misinterpret GraphQL responses or fail to handle errors properly, leading to poor user experiences or bugs. Knowing how GraphQL handles errors helps build more resilient applications that can gracefully manage partial failures.

Where it fits

Learners should first understand basic REST API error handling and HTTP status codes. After this, they can explore GraphQL query structure and response format. Later, they can learn advanced error handling patterns and client-side error management in GraphQL.

Mental Model

Core Idea

GraphQL separates data and errors in one response, allowing partial success, unlike REST which uses HTTP status codes to signal full success or failure.

Think of it like...

Imagine ordering a meal where the waiter brings you the parts that are ready and tells you which dishes are delayed, instead of canceling the whole order because one dish is missing.

┌───────────────┐
│ GraphQL Resp. │
├───────────────┤
│ data: {...}   │
│ errors: [...] │
└───────────────┘

vs.

┌───────────────┐
│ REST Response │
├───────────────┤
│ HTTP Status   │
│ Body: data or │
│ error message │
└───────────────┘

Build-Up - 6 Steps

1

Foundation

Basics of REST Error Handling

Concept: REST APIs use HTTP status codes to indicate success or failure of requests.

In REST, when you make a request, the server responds with a status code like 200 for success or 404 for not found. The response body usually contains data if successful or an error message if not.

Result

Clients know if the request succeeded or failed by checking the HTTP status code.

Understanding HTTP status codes is essential because REST relies on them to communicate error states clearly.

2

Foundation

GraphQL Response Structure

Concept: GraphQL responses always return a 200 HTTP status but include errors inside the response body.

A GraphQL response has two main parts: 'data' with the requested info and 'errors' with any problems encountered. Even if some fields fail, the server returns partial data with error details.

Result

Clients receive both data and error information together, allowing partial success.

Knowing that GraphQL uses a single HTTP status code for all responses changes how you check for errors.

3

Intermediate

Partial Success in GraphQL

🤔Before reading on: do you think GraphQL returns either full data or no data at all? Commit to your answer.

Concept: GraphQL allows partial data to be returned even if some parts of the query fail.

If a query requests multiple fields and one field has an error, GraphQL returns data for the successful fields and error details for the failed ones. This lets clients use available data without failing completely.

Result

Clients can display partial results and handle errors more gracefully.

Understanding partial success helps build user interfaces that remain responsive despite backend issues.

4

Intermediate

Error Location and Path in GraphQL

🤔Before reading on: do you think GraphQL errors just say 'something went wrong' or provide more detail? Commit to your answer.

Concept: GraphQL errors include detailed information about where in the query the error happened.

Each error object in GraphQL has fields like 'message', 'locations' (line and column), and 'path' (which field caused the error). This helps clients pinpoint and handle errors precisely.

Result

Developers get clear insights into which part of the query failed.

Knowing error locations enables better debugging and user feedback.

5

Advanced

Handling Network vs. GraphQL Errors

🤔Before reading on: do you think network errors and GraphQL errors are handled the same way? Commit to your answer.

Concept: Network errors and GraphQL errors are distinct and require different handling strategies.

Network errors occur when the request fails to reach the server (e.g., no internet). GraphQL errors happen when the server processes the request but finds issues in the query or data. Clients must check for both separately.

Result

Robust clients can distinguish and respond appropriately to different error types.

Separating network and GraphQL errors prevents confusion and improves reliability.

6

Expert

Custom Error Handling Strategies in GraphQL

🤔Before reading on: do you think GraphQL servers must always return all errors or can they customize error responses? Commit to your answer.

Concept: GraphQL servers can customize error reporting and use extensions to provide richer error info.

Advanced GraphQL implementations add custom error codes, severity levels, or user-friendly messages in the 'extensions' field of errors. This allows clients to implement nuanced error handling and user notifications.

Result

Applications can provide better user experiences by tailoring error feedback.

Understanding custom error extensions unlocks powerful error management beyond basic messages.

Under the Hood

GraphQL servers always respond with HTTP 200 status to indicate the request was processed. Errors are embedded in the response body under the 'errors' key, alongside any partial 'data'. This design separates transport-level success from application-level errors, allowing clients to parse both simultaneously.

Why designed this way?

This approach was chosen to support complex queries that may partially succeed. Unlike REST, which treats each request as atomic, GraphQL queries can request multiple fields, so returning partial data with errors improves flexibility and user experience.

┌───────────────┐
│ Client Query  │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ GraphQL Server│
│ Processes all │
│ fields        │
├──────┬────────┤
│ Data │ Errors │
└──────┴────────┘
       │
       ▼
┌─────────────────────────────┐
│ HTTP 200 Response            │
│ {                           │
│   data: {...},              │
│   errors: [{message, path}] │
│ }                           │
└─────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think a GraphQL response with errors always means the entire request failed? Commit yes or no.

Common Belief: If there are errors in a GraphQL response, the whole request failed and no data is usable.

Reality: GraphQL can return partial data alongside errors, so some data may be valid and usable even if errors exist.

Why it matters: Assuming all data is invalid leads to discarding useful information and poor user experience.

Quick: Do you think HTTP status codes in GraphQL indicate query success or failure? Commit yes or no.

Common Belief: GraphQL uses HTTP status codes like REST to indicate if a query succeeded or failed.

Reality: GraphQL typically returns HTTP 200 for all responses, using the response body to indicate errors.

Why it matters: Relying on HTTP status codes alone causes missed errors and incorrect client behavior.

Quick: Do you think network errors and GraphQL errors are the same? Commit yes or no.

Common Belief: All errors in GraphQL are handled the same way, whether network or query errors.

Reality: Network errors prevent any response, while GraphQL errors come inside a successful HTTP response and must be handled separately.

Why it matters: Confusing these leads to improper error handling and unreliable applications.

Quick: Do you think GraphQL error messages always contain full debugging info? Commit yes or no.

Common Belief: GraphQL error messages always provide detailed debugging information to clients.

Reality: Error details can be limited for security or privacy reasons; servers may customize or omit sensitive info.

Why it matters: Expecting full details can cause confusion and security risks if sensitive info is exposed.

Expert Zone

1

GraphQL error 'extensions' field allows servers to send structured metadata, enabling clients to implement fine-grained error handling.

2

Partial data with errors can cause subtle bugs if clients do not check for errors before using data fields.

3

Some GraphQL clients provide built-in mechanisms to merge partial data and errors, but developers must understand underlying response structure to customize behavior.

When NOT to use

GraphQL error handling is less suitable when strict atomicity is required, such as financial transactions needing full success or failure. In such cases, REST or RPC with strict status codes and rollback mechanisms may be better.

Production Patterns

In production, teams often implement custom error codes in 'extensions', use middleware to format errors consistently, and build client logic to display partial data with user-friendly error messages. Monitoring tools track error rates separately from HTTP status codes.

Connections

HTTP Status Codes

GraphQL builds on HTTP but diverges in error signaling.

Understanding HTTP status codes helps grasp why GraphQL uses a single 200 status and embeds errors in the body.

Partial Failure Handling in Distributed Systems

GraphQL's partial success model is similar to how distributed systems handle partial failures.

Knowing distributed system fault tolerance clarifies why GraphQL returns partial data with errors instead of all-or-nothing.

User Experience Design

Error handling strategies directly impact how users perceive application reliability.

Understanding UX principles helps developers design error displays that leverage GraphQL's partial data for smoother user interactions.

Common Pitfalls

#1 Ignoring the 'errors' field and assuming all data is valid.

Wrong approach:

{ "data": { "user": null }, "errors": [{ "message": "User not found" }] } // Client uses data.user without checking errors

Correct approach:

Check if 'errors' exist before using 'data'; handle or display errors appropriately.

Root cause:

Misunderstanding that GraphQL can return data and errors together leads to unsafe data usage.

#2 Relying on HTTP status codes to detect GraphQL errors.

Wrong approach:

if (response.status === 200) { useData(response.data); } else { showError(); }

Correct approach:

Always check response body for 'errors' field even if status is 200.

Root cause:

Assuming GraphQL behaves like REST causes missed error detection.

#3 Treating network errors and GraphQL errors the same way.

Wrong approach:

try { fetchGraphQL() } catch { showGenericError(); } // No separate handling for GraphQL errors

Correct approach:

Catch network errors separately; check response for GraphQL errors and handle accordingly.

Root cause:

Confusing transport-level failures with application-level errors leads to poor error management.

Key Takeaways

GraphQL error handling differs from REST by returning errors inside a 200 HTTP response alongside partial data.

Clients must check the 'errors' field in GraphQL responses to detect and handle problems properly.

Partial success allows applications to use available data even when some parts fail, improving user experience.

Network errors and GraphQL errors are distinct and require separate handling strategies.

Advanced GraphQL servers can customize error details to provide richer context for clients.

Practice

1. In GraphQL, how are errors handled differently compared to REST APIs?

easy

A. GraphQL returns data and errors together in one response.

B. GraphQL stops execution and returns only errors without data.

C. GraphQL returns errors as HTTP status codes only.

D. GraphQL does not provide any error details to the client.

Solution

1. Step 1: Understand REST error handling

   REST APIs usually return errors as HTTP status codes and no data when an error occurs.

2. Step 2: Understand GraphQL error handling

   GraphQL returns both data and errors together in one response, allowing partial data delivery.

3. Final Answer:

   GraphQL returns data and errors together in one response. -> Option A

4. Quick Check:

   GraphQL response = data + errors [OK]

Hint: Remember GraphQL sends data and errors together [OK]

Common Mistakes:

• Thinking GraphQL only returns errors without data
• Confusing HTTP status codes with GraphQL error handling
• Assuming GraphQL hides error details

2. Which part of a GraphQL response contains error details?

easy

A. The data field

B. The HTTP status code

C. The errors field

D. The extensions field only

Solution

1. Step 1: Identify error location in GraphQL response

   GraphQL responses include an errors field that lists error messages and details.

2. Step 2: Differentiate from other fields

   The data field contains the requested data, HTTP status codes are not used for errors, and extensions may have extra info but not main errors.

3. Final Answer:

   The errors field -> Option C

4. Quick Check:

   Error details = errors field [OK]

Hint: Errors are always in the 'errors' field [OK]

Common Mistakes:

• Looking for errors in the data field
• Relying on HTTP status codes for errors
• Confusing extensions with errors

3. Given this GraphQL response:

{"data": {"user": null}, "errors": [{"message": "User not found", "path": ["user"]}]}

What does this response mean?

medium

A. The user exists but has no data.

B. The query failed completely and no data is returned.

C. The server returned a syntax error in the query.

D. Partial data is returned; user field is null due to an error.

Solution

1. Step 1: Analyze the data field

   The data field shows "user": null, meaning no user data was returned.

2. Step 2: Analyze the errors field

   The errors field shows "User not found" with path ["user"], indicating an error related to the user field.

3. Final Answer:

   Partial data is returned; user field is null due to an error. -> Option D

4. Quick Check:

   Partial data + error path = null field [OK]

Hint: Null data with errors means partial failure [OK]

Common Mistakes:

• Assuming no data means full failure
• Ignoring the errors field
• Thinking user exists without data

4. You receive this GraphQL response:

{"data": {"post": {"title": "Hello World"}}, "errors": [{"message": "Author not found", "path": ["post", "author"]}]}

What is the likely issue?

medium

A. The post data is returned but author field caused an error.

B. The server returned no data at all.

C. The entire query failed due to syntax error.

D. The author field is missing from the query.

Solution

1. Step 1: Check the data field

   The data field contains post with a title, so some data is returned.

2. Step 2: Check the errors field

   The error message "Author not found" with path ["post", "author"] shows the error is specific to the author field inside post.

3. Final Answer:

   The post data is returned but author field caused an error. -> Option A

4. Quick Check:

   Data present + error path = partial error [OK]

Hint: Error path shows which field failed [OK]

Common Mistakes:

• Assuming full query failure
• Ignoring error path details
• Thinking missing field means query error

5. Why does GraphQL include the error path in its error messages?

hard

A. To replace HTTP status codes for error classification.

B. To indicate the exact field causing the error for better client handling.

C. To hide sensitive server information from clients.

D. To provide a list of all fields in the query.

Solution

1. Step 1: Understand the purpose of error path

   The path shows the exact location in the query where the error happened.

2. Step 2: Understand client benefit

   This helps clients know which part of the data failed and handle partial data properly.

3. Final Answer:

   To indicate the exact field causing the error for better client handling. -> Option B

4. Quick Check:

   Error path = pinpoint error location [OK]

Hint: Error path points to problem field [OK]

Common Mistakes:

• Thinking path replaces HTTP status codes
• Assuming path hides server info
• Confusing path with full query fields