Persisted query missing from registry returns inconsistent HTTP status

Direct answer

The GraphQL specification does not define an HTTP status code for an unknown persisted-query ID. A missing registry entry is a client request error, so 400 Bad Request is the more useful default. A 200 OK response containing a GraphQL errors array is legal but makes client handling fragile. If you operate a gateway, normalize upstream variance to a single contract before clients see it.

Confirmed facts versus likely explanation

Confirmed

• The GraphQL specification governs query execution and response shape, not HTTP status codes for persisted-query lookup.
• Server implementations diverge: some return 400, while others return 200 with a GraphQL errors array.
• HTTP status alone cannot reliably identify a registry miss across different servers or versions.

Likely explanation

A missing persisted-query ID is usually detected before execution, which many servers classify as a bad request. Other implementations treat lookup failure as an execution error and still return HTTP 200 because the transport request itself was well-formed.

Steps for this case

1. Send a request with a non-existent persisted-query ID to the GraphQL endpoint and record the status code and body.
2. Inspect the JSON body for an errors array and any extensions.code field.
3. If you control the server, configure it to return 400 with a stable code such as PERSISTED_QUERY_NOT_FOUND.
4. If you cannot change the server, place a gateway in front and map every upstream registry-miss signature to the same client-facing response.

Recommended normalized gateway response

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "errors": [
    {
      "message": "Persisted query not found",
      "extensions": {
        "code": "PERSISTED_QUERY_NOT_FOUND"
      }
    }
  ]
}

Client detection

Do not branch only on HTTP status. Check status first, then inspect errors[].extensions.code. Treat 400 with PERSISTED_QUERY_NOT_FOUND as a registry miss; treat other 400s as malformed requests; treat 200 with errors as server-specific unless normalized by a gateway.

Verification command

curl -i -X POST https://api.example.com/graphql -H "Content-Type: application/json" -d '{"extensions": {"persistedQuery": {"sha256Hash": "deadbeef..."}}}'

Compare the status and body against the expected normalized shape. If the upstream returns 200, the gateway must rewrite it to 400 before forwarding to clients.

Assumption: you are using HTTP transport for GraphQL and can insert a gateway or middleware. Version-specific defaults may change; verify after upgrades.