GraphQL http status codes proper error handling guide

GraphQL HTTP status codes work differently from REST: a GraphQL server returns HTTP 200 OK for almost every request — including ones with errors. The request reached the server and was processed; any query-level failures appear inside the JSON body in a dedicated errors array, often alongside partial data that did resolve successfully.

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

Introduction to GraphQL error handling

When developers move from REST to GraphQL, error handling is one of the sharpest adjustments. REST uses HTTP status codes as the primary signal — 404 means resource missing, 500 means server fault. GraphQL replaces that model with a two-layer system: HTTP codes handle transport concerns, and the response body handles everything else.

This happens because GraphQL routes all operations through a single endpoint. Since the URL never changes, it cannot carry the semantic meaning that REST endpoint paths do. Instead, the response JSON carries that meaning inside data and errors fields.

The partial-success model is one of GraphQL’s real strengths. Imagine a dashboard query that fetches user profile, recent orders, and notifications. If the orders service is down, a REST client gets a 503 and loses everything. A GraphQL client gets a 200 OK with the profile and notifications intact plus an error entry for orders — the page still renders meaningfully. This is why adapting your error-handling logic matters before going to production.

GraphQL’s approach to HTTP status codes

The GraphQL specification is deliberate about this: 200 OK should be returned whenever the server successfully receives and begins executing a request, even if resolvers fail. The HTTP layer answers the question “did the request arrive and get processed?” — the errors array answers “did the query logic succeed?”

This separation has a practical benefit for monitoring. You can configure infrastructure alerts on 5xx rates to catch server-level outages, and separately configure application-level alerts that parse the GraphQL errors array in 200 responses to track resolver failures, validation issues, and auth problems. Conflating the two leads to blind spots in production.

HTTP methods in GraphQL

GraphQL recommends POST for all operations. It supports request bodies of any size, keeps variables and sensitive data out of URLs, and works without URL-length constraints. GET can be used for simple read-only queries where caching is desirable, but mutations must always use POST — using GET for a mutation is both semantically wrong and a security risk since the URL may get logged, cached, or prefetched by browsers.

When GraphQL returns non-200 status codes

Non-200 responses indicate that something stopped the request before GraphQL execution started. These are the scenarios and the correct status to use for each:

A common mistake is returning 500 for individual resolver failures. If the database is slow and one field resolver times out, that is an application-level problem — it should return 200 OK with an error in the errors array, not a 500. Reserve 500 for situations where the GraphQL server process itself is down or panicked.

/* 400 — query cannot be parsed */
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "errors": [{ "message": "Syntax Error: Expected Name, found }." }]
}

/* 200 — query parsed, but resolver failed */
HTTP/1.1 200 OK
Content-Type: application/graphql-response+json

{
  "data": { "order": null },
  "errors": [{ "message": "Database timeout", "path": ["order"] }]
}

The GraphQL error response structure

The errors array is where GraphQL communicates application-level problems. Each item follows the structure defined by the GraphQL specification. The only required field is message; everything else is optional but valuable in production systems.

{
  "data": {
    "user": {
      "name": "Alex",
      "orders": null
    }
  },
  "errors": [
    {
      "message": "Failed to load orders: connection refused",
      "locations": [{ "line": 4, "column": 5 }],
      "path": ["user", "orders"],
      "extensions": {
        "code": "SERVICE_UNAVAILABLE",
        "retryable": true,
        "requestId": "req_8f3k2m"
      }
    }
  ]
}

The path field is especially useful. A value of ["user", "orders", 2, "title"] tells you exactly that the title field on the third order item failed — not that “something about orders went wrong.” This precision lets clients handle failures at the right granularity rather than degrading the entire screen.

The extensions field is where well-designed APIs add machine-readable codes like "code": "NOT_FOUND" or "code": "RATE_LIMITED". Clients can act on these codes programmatically — showing a login prompt, triggering a retry after a delay, or logging the requestId for support correlation — without parsing fragile human-readable strings.

Error object anatomy

Breaking down each field in a real error object helps clarify what clients should do with the information:

In development environments it is reasonable to include stack traces inside extensions.stacktrace. In production, strip them entirely — stack traces expose file paths, library versions, and internal logic that attackers can exploit. The requestId gives you the correlation capability without the exposure.

Common HTTP error scenarios in GraphQL

Different errors arise at different points in the request pipeline. Knowing when an error occurs determines how it should be returned.

The dividing line is GraphQL execution. Errors that happen before execution — parsing, auth middleware, method validation — get HTTP status codes. Errors that happen during execution — resolver failures, field authorization, data validation — get entries in the errors array with a 200 OK.

Request parsing and validation errors

GraphQL processes requests in two distinct phases before any resolver runs:

Validation errors are worth surfacing clearly to API consumers. A message like Cannot query field "emailAddress" on type "User". Did you mean "email"? saves significant debugging time. These appear in the errors array automatically in all major GraphQL servers and should not be suppressed in development or staging environments.

Authentication and authorization errors

GraphQL’s field-level resolution model makes auth more nuanced than REST. You need a clear rule for when to use an HTTP status code versus an error in the array.

The industry-standard error codes from Apollo and graphql-errors libraries are UNAUTHENTICATED (needs to log in) and FORBIDDEN (logged in but not allowed). Adopting these codes makes your API predictable for client developers and compatible with standard GraphQL tooling.

{
  "data": { "viewer": { "name": "Alex", "billingInfo": null } },
  "errors": [
    {
      "message": "Not authorized to access billing information",
      "path": ["viewer", "billingInfo"],
      "extensions": { "code": "FORBIDDEN" }
    }
  ]
}

Server and resolver errors

Individual resolver failures should almost always return 200 OK with a descriptive error entry — not a 500. A database timeout on one field does not mean the server is down; other fields in the same query may resolve perfectly. Returning 500 here misleads monitoring systems and loses partial data that the client could have used.

Reserve 500 Internal Server Error for situations where the GraphQL server process itself cannot handle any requests: memory exhaustion, unhandled exceptions at startup, crashed worker processes. In those cases the server typically cannot produce a valid GraphQL response at all.

In production, sanitize error messages from resolvers before they reach the client. A message like Error: connect ECONNREFUSED 10.0.1.4:5432 exposes your internal network topology. Replace it with Service temporarily unavailable and log the original internally alongside the requestId from extensions.

Best practices for GraphQL error handling

Client-side implementation should follow a consistent pattern: check HTTP status first (handle 4xx/5xx), then check for an errors array (handle application errors), then process data (render successfully resolved fields). Never skip the middle step just because the HTTP status is 200.

async function graphqlRequest(query, variables) {
  const res = await fetch('/graphql', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query, variables }),
  });

  // Transport-level failure
  if (!res.ok) {
    throw new Error(`HTTP ${res.status}: ${res.statusText}`);
  }

  const json = await res.json();

  // Application-level errors — still a 200 OK
  if (json.errors?.length) {
    json.errors.forEach(err => {
      console.error(`[${err.extensions?.code}] ${err.message}`, err.path);
    });
  }

  // Return both data and errors; let the caller decide
  return json;
}

For monitoring, configure your observability tools to parse response bodies, not just HTTP codes. A GraphQL API can show 100% HTTP success while 30% of queries are failing at the resolver level — invisible to any monitor watching only status codes. Platforms like Datadog, New Relic, and Grafana all support custom metric extraction from response payloads.