How to Return Partial Data with Errors in GraphQL

In GraphQL, you can return partial data with errors by including both the data and errors fields in the response. The data field contains whatever data could be resolved, while the errors field lists the problems encountered during execution, allowing clients to receive partial results alongside error details.

Syntax

A GraphQL response that returns partial data with errors includes two main parts:

• data: Contains the successfully resolved parts of the query.
• errors: An array of error objects describing what went wrong.

This structure allows clients to process available data even if some parts failed.

json

{
  "data": {
    "user": {
      "id": "123",
      "name": "Alice"
    }
  },
  "errors": [
    {
      "message": "Failed to fetch user's posts",
      "path": ["user", "posts"],
      "locations": [{"line": 5, "column": 7}]
    }
  ]
}

Example

This example shows a GraphQL query requesting a user's id, name, and posts. If fetching posts fails, the server returns the id and name but includes an error for posts.

graphql

query {
  user(id: "123") {
    id
    name
    posts {
      title
    }
  }
}

// Server response:
{
  "data": {
    "user": {
      "id": "123",
      "name": "Alice",
      "posts": null
    }
  },
  "errors": [
    {
      "message": "Failed to fetch user's posts",
      "path": ["user", "posts"],
      "locations": [{"line": 5, "column": 5}]
    }
  ]
}

Output

{
  "data": {
    "user": {
      "id": "123",
      "name": "Alice",
      "posts": null
    }
  },
  "errors": [
    {
      "message": "Failed to fetch user's posts",
      "path": ["user", "posts"],
      "locations": [{"line": 5, "column": 5}]
    }
  ]
}

Common Pitfalls

Common mistakes when returning partial data with errors include:

• Not including the errors field, which hides problems from the client.
• Returning null for a field without an error, causing confusion.
• Failing to specify the path in error objects, making it hard to identify which part failed.

Always include clear error messages and paths to help clients handle partial data correctly.

json

/* Wrong: Missing errors field */
{
  "data": {
    "user": {
      "id": "123",
      "name": "Alice",
      "posts": null
    }
  }
}

/* Right: Include errors with path */
{
  "data": {
    "user": {
      "id": "123",
      "name": "Alice",
      "posts": null
    }
  },
  "errors": [
    {
      "message": "Failed to fetch user's posts",
      "path": ["user", "posts"]
    }
  ]
}

Quick Reference

Field	Description
data	Contains the successfully fetched data, may have nulls for failed fields
errors	Array of error objects describing issues during query execution
errors.message	Human-readable error message
errors.path	Array showing the location of the error in the query
errors.locations	Optional array indicating where in the query the error occurred

Key Takeaways

GraphQL responses can include both partial data and errors together.

Always include the errors array with clear messages and paths for failed fields.

Partial data helps clients show available information even if some parts fail.

Null values in data should be accompanied by corresponding errors for clarity.

Use the errors.path field to pinpoint exactly which part of the query failed.