Skip to content

GraphQL errors

Read data and errors, tell error codes apart and handle GraphQLResponseError.

Every response is JSON with data and, when a field failed, errors. A response with HTTP 200 can contain errors: check it before you read data.

Response shape

A successful execution contains only data:

Successful response
{
  "data": {
    "store": {
      "id": "7204558912004325301",
      "name": "My store"
    }
  }
}

When a field fails, errors explains why and that field comes back as null. If the field is non-null, the null propagates up to data:

Response with an error
{
  "errors": [
    {
      "message": "Product ID is invalid.",
      "path": ["relatedProducts"],
      "extensions": {
        "code": "BAD_USER_INPUT"
      }
    }
  ],
  "data": null
}
FieldContent
dataThe fields that resolved.
errors[].messageDiagnostic text. It can change.
errors[].pathThe field that failed.
errors[].extensions.codeStable code to branch on.

Branch on extensions.code. Syntax and document validation errors use the standard GraphQL codes.

Codes

CodeCauseWhat to do
BAD_USER_INPUTAn argument, filter, limit or ID is invalid.Fix the input before retrying.
NOT_FOUNDThe product, collection or seller doesn't exist in the store or isn't published.Check the slug or ID and the store in x-Store-Domain.
STORE_CONTEXT_REQUIREDx-Store-Domain is missing or doesn't match a store.Send the store's slug or a configured domain.

With fetch

Check the HTTP status, then errors:

graphql-fetch.js
const response = await fetch("https://storefront.ecomiq.pe/graphql", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-Store-Domain": "my-store",
  },
  body: JSON.stringify({
    query: "query Store { store { id name } }",
  }),
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}

const result = await response.json();

if (result.errors?.length) {
  const [error] = result.errors;

  switch (error.extensions?.code) {
    case "BAD_USER_INPUT":
      console.error("Fix the query arguments.");
      break;
    case "NOT_FOUND":
      console.error("The resource doesn't exist in this store.");
      break;
    case "STORE_CONTEXT_REQUIRED":
      console.error("Check x-Store-Domain.");
      break;
    default:
      console.error(error.message);
  }

  throw new Error(error.message);
}

console.log(result.data.store);

With @ecomiq/core

graphql() validates data with the Zod schema you pass. It throws GraphQLResponseError when the response contains errors, has no data, or data doesn't match the schema; in that last case the code is INVALID_RESPONSE.

graphql-client.ts
import { createClient, GraphQLResponseError } from "@ecomiq/core";
import { z } from "zod";

const SellerData = z.object({
  seller: z.object({
    id: z.string(),
    name: z.string(),
    slug: z.string(),
  }),
});

const api = createClient({ domain: "my-store" });

try {
  const data = await api.graphql(
    `
      query Seller($slug: String!) {
        seller(slug: $slug) { id name slug }
      }
    `,
    SellerData,
    { slug: "acme" },
  );

  console.log(data.seller);
} catch (error) {
  if (!(error instanceof GraphQLResponseError)) {
    throw error;
  }

  for (const graphQLError of error.errors) {
    console.error(graphQLError.extensions?.code, graphQLError.message);
  }
}

error.errors holds the error list and error.data any partial data that arrived.

Next steps

Last updated:

On this page