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.