Error handling

GraphQL queries and mutations can generate errors that fall into two categories - developer errors and user errors. Developer errors occur when you try to customize applications that use our GraphQL APIs. They indicate that something went wrong during the request, which could be due to a server issue such as a server exception, dependency issues, or an issue in the developer's integration such as unauthorized access or an entity not found. Such errors can occur with both queries and mutations.

We’ve tried to cover some of these errors in this section.

Error type/description	Extension code
Input Format Errors - Example: An empty string is provided as an input for cartId	BAD_REQUEST
Graphql syntax errors - Example: Sub-fields of an object are not provided for a query/mutation	GRAPHQL_VALIDATION_FAILED
Entity not found - Example: The client lacks valid authentication credentials but requests a field which at a minimum requires authentication	NOT_FOUND
Authentication or authorization issues - Example: The client lacks valid authentication credentials but requests a field which at a minimum requires authentication	UNAUTHORIZED
Client has insufficient authorization permissions to perform an action - Example: The bearer token provided in the authorization header doesn’t have necessary permissions to perform a action	FORBIDDEN
Query cost limit exceeded - Example: The client has exceeded the allowed limit for a single request	RESOURCE_LIMIT_EXCEEDED
Rate limit exceeded - The client has exceeded the allowed limit for multiple requests during a given period of time	RATE_LIMIT_EXCEEDED
Server errors*	INTERNAL_SERVER_ERROR

For example:

Mutation:

mutation applyDiscountToCart($input: ApplyDiscountInput!) {
  applyDiscountToCart(input: $input) {
    cart {
      id
      items {
        id
      }
    }
  }
}

Input:

{
  "input": {
    "cartId": "",
    "discountCode": "FOOBAR"
  }
}

Output:

{
  "errors": [
    {
      "message": "cartId cannot be empty",
      "path": [
        "applyDiscountToCart"
      ],
      "extensions": {
        "code": "BAD_REQUEST"
      }
    }
  ],
  "data": {
    "applyDiscountToCart": null
  }
}

Other errors

In addition to some of the common errors mentioned above, you may also encounter other errors based on your inputs and due to validation issues related to business rules. For instance, if you try to apply an invalid discount code while placing an order, the mutation will return an error. We've covered some of these errors as well in the respective sections for mutations.