Uptimy
All Articles
Protocols··7 min read

GraphQL Monitoring: Why 200 OK Doesn't Mean the Query Worked

GraphQL reports most failures inside a 200 response, so status checks stay green while queries fail. What a real GraphQL health check runs, checks, and alerts on.

You point an uptime check at /graphql, it stays green, and the dashboard your customers use is broken. Nothing is wrong with the check. GraphQL reports most failures inside a successful HTTP response, and a check that only reads the status code never sees them.

How GraphQL Reports a Failure

When a resolver fails, say the orders service times out, a GraphQL server still answers 200 OK. The failure is in the body:

HTTP 200 OK
{
  "data": { "orders": null },
  "errors": [
    {
      "message": "Timeout fetching orders",
      "path": ["orders"],
      "extensions": { "code": "INTERNAL_SERVER_ERROR" }
    }
  ]
}

Three details make this easy to miss:

  • Results can be partial. One field fails and the rest succeed. A failed field that can be null becomes null; if it can't be null, the error nulls its parent instead, up to data itself.
  • Bad requests vary by server. A query with an unknown field gets a 200 with errors from some servers and a 400 from others, depending on the server and the response format the client asked for.
  • Errors don't raise the status. A broken database, an expired downstream token or a failing resolver all arrive as entries in errors, next to a 200.

So the status code tells you the server answered, nothing more. This is the GraphQL version of a problem every API has: HTTP 200 is not a health check.

What a GraphQL Health Check Should Do

1. Run a query that touches real data

{ __typename } proves the server is up and can parse a query. It doesn't call a single resolver. Query the fields your app depends on, so the check goes through the same resolvers and data sources your users hit.

2. Fail on any GraphQL error

A non-empty errors list means part of the query failed, whatever the status code says. Some servers always send errors, empty when everything worked, so check for entries, not for the key.

3. Check the data, not just the absence of errors

A resolver can succeed and still return nothing useful: an empty list because a tenant lookup failed, or a null from a cache that was flushed. Require the fields you need: that a known record has the value you expect, or that a list has at least one item.

4. Watch the response time

GraphQL makes it easy to fetch a lot in one request, and a resolver that fans out into one query per item gets slower as data grows. A response time limit catches that before it turns into timeouts.

5. Let the query catch breaking schema changes

If a deploy removes or renames a field your clients use, a query that asks for it fails validation and returns an error. A check that runs the same fields as your clients turns that into an alert, without diffing schemas.

Choosing the Query

  • Read-only. Avoid mutations unless they're idempotent and write to test data. A check runs from several regions every minute.
  • Small. One or two fields per area you care about, no deep nesting, no pagination. The check should be cheap enough that nobody thinks twice about running it.
  • Predictable. Query a known record by ID, owned by a monitoring account, so you can check an exact value rather than just that something came back.
Health check query
query HealthCheck {
  viewer { id }
  product(id: "monitoring-fixture") { id name inStock }
  orders(first: 1) { id }
}

This exercises authentication (viewer), the catalog, and the orders service in one request, each with a field you can check.

Setting It Up in Uptimy

Create a healthcheck and pick the GraphQL type. Enter the Endpoint URL, then put your query and any headers, such as Authorization, under Advanced settings.

Two rules apply to every GraphQL check, with or without checks of your own:

  • The status must be 2xx, unless you add a status code check.
  • Any GraphQL error fails the check. An empty errors list is fine.

Under Checks, click Add check to require the data: JSON field data.viewer.id exists, JSON field data.product.inStock equals true, JSON field data.orders.0.id exists, and Response time is below 1000 ms. Paths start at the whole response, so they begin with data, and a number picks an item from a list.

When a run fails, the result and the incident say which rule broke and what came back. A deploy that renamed orders, and a product that went out of stock, look like this:

Failed checks
GraphQL query returned errors: Cannot query field "orders" on type "Query".

JSON field data.product.inStock equals true
got false

Through the API or uptimyctl, the same check is:

GraphQL check config
{
  "uri": "https://api.example.com/graphql",
  "query": "query HealthCheck { viewer { id } product(id: \"monitoring-fixture\") { id name inStock } orders(first: 1) { id } }",
  "headers": { "Authorization": "Bearer ..." },
  "assertions": [
    { "source": "json", "path": "data.viewer.id", "op": "exists" },
    { "source": "json", "path": "data.product.inStock", "op": "eq", "value": true },
    { "source": "json", "path": "data.orders.0.id", "op": "exists" },
    { "source": "response_time", "op": "lt", "value": 1000 }
  ]
}

Variables go in the config as variables, through the API or uptimyctl. See the GraphQL check docs for every field.

✅

When the token expires

A GraphQL check sends the same headers every time. If your API needs a fresh token from a login, use a multi-step API check instead: log in, then POST the query as a JSON body with Authorization: Bearer {{token}}. HTTP checks don't know about GraphQL errors, so add JSON field errors.0 does not exist to that request: it passes when there's no errors list and when it's empty.

📌Key Takeaways

  • 1GraphQL reports most failures inside a 200 response, in the errors list
  • 2{ __typename } proves the server is up, not that any resolver works
  • 3Fail on any GraphQL error, then check the data fields you depend on
  • 4A query that uses your clients' fields catches breaking schema changes
  • 5Keep the query small, read-only, and pointed at a known record

23:00 · goodnight

All systems operational

Stop wondering if production is okay.

Tonight, if something breaks, you will know first — with the context to fix it and a status page that keeps customers informed. And if nothing breaks, you get to sleep.

Free plan available · No credit card required · Cancel anytime