Handling Errors

This article explains how to handle different types of errors in GraphQL API

Validation Errors

If you use an input parameter that fails validation in the mutation the API will return a validation error. You can use the errors field in the mutation to access those validation errors. The type of errors field is a list of ModelValidationError object.

Here is an example response for an updateAddressDetails mutation.

GraphQL mutation

mutation($input: UpdateAddressDetailsInput!) {
    updateAddressDetails(input: $input){
        subscription {
            id
        }
        errors {
            attribute
            message
            path
        }
    }
}

Note that you need to include errors field in the query to retrieve the validation errors.

GraphQL Variables

{
    "input": {
        "name": "John Doe",
        "email": "johndoe",
        "address": "X street",
        "city": "test",
        "country": "XXXXXX",
        "termsAccepted": true
    }
}

Response

{
    "data": {
        "updateAddressDetails": {
            "subscription": {
                "id": "0"
            },
            "errors": [
                {
                    "attribute": "country",
                    "message": "not allowed",
                    "path": null
                },
                {
                    "attribute": "email",
                    "message": "Your email address is invalid",
                    "path": null
                }
            ]
        }
    }
}

As you can see in the sample response, if one of the input parameters fails validation it will show up on the data.<mutation_name>.errors field.

Not Found Errors

If the resource you are trying to access is not found, the GraphQL query will result in an error. In this case, the errors field will be directly in the root. You can check if the thrown error is a not found error by checking if the extensions.code field is RECORD_NOT_FOUND

GraphQL mutation

mutation UpdateOrderedProductQuantity($input: UpdateOrderedProductQuantityInput!) {
    updateOrderedProductQuantity(input:$input) {
        orderedProduct { 
            id
            quantity
            title
        }
    }
}

GraphQL variables

{
    "input": {
        "orderedProduct": {
            "id": "invalid",
            "quantity": 0
        }
    }
}

GraphQL response

{
    "data": {
        "updateOrderedProductQuantity": null
    },
    "errors": [
        {
            "message": "Ordered product not found",
            "locations": [
                {
                    "line": 2,
                    "column": 5
                }
            ],
            "path": [
                "updateOrderedProductQuantity"
            ],
            "extensions": {
                "code": "RECORD_NOT_FOUND"
            }
        }
    ]
}

Note that the errors field is in the root of the object and not under data.updateOrderedProductQuantity.

Unauthorized Errors

If you are using a token with Storefront access type, you don't have access to some query and mutations. If that's the case the API will return an Unauthorized error. You can check if the error is an unauthorized error by checking if the extensions.code field is UNAUTHORIZED.

GraphQL query

mutation CreateAsset {
    createAsset(input: { productId: "1", internalNumber: "1" }) {
        asset {
          id
        }
    }
}

GraphQL response

{
    "data": {
        "createAsset": null
    },
    "errors": [
        {
            "message": "Not allowed",
            "locations": [
                {
                    "line": 2,
                    "column": 5
                }
            ],
            "path": [
                "createAsset"
            ],
            "extensions": {
                "code": "UNAUTHORIZED"
            }
        }
    ]
}

Other Errors

If you use a malformed query, such as one with invalid field names or missing required parameters, the API will report this in the errors field. You can determine what actually went wrong by checking the message property of the error.

Here are some examples of common errors:

{
    "errors": [
        {
            "message": "Argument 'productId' on InputObject 'CreateAssetInput' is required. Expected type ID!",
            "locations": [
                {
                    "line": 2,
                    "column": 24
                }
            ],
            "path": [
                "mutation CreateAsset",
                "createAsset",
                "input",
                "productId"
            ],
            "extensions": {
                "code": "missingRequiredInputObjectAttribute",
                "argumentName": "productId",
                "argumentType": "ID!",
                "inputObjectType": "CreateAssetInput"
            }
        },
        {
            "message": "Field must have selections (field 'asset' returns Asset but has no selections. Did you mean 'asset { ... }'?)",
            "locations": [
                {
                    "line": 4,
                    "column": 9
                }
            ],
            "path": [
                "mutation CreateAsset",
                "createAsset",
                "asset"
            ],
            "extensions": {
                "code": "selectionMismatch",
                "nodeName": "field 'asset'",
                "typeName": "Asset"
            }
        },
        {
            "message": "Field 'invalidMutation' doesn't exist on type 'Mutation'",
            "locations": [
                {
                    "line": 7,
                    "column": 5
                }
            ],
            "path": [
                "mutation CreateAsset",
                "invalidMutation"
            ],
            "extensions": {
                "code": "undefinedField",
                "typeName": "Mutation",
                "fieldName": "invalidMutation"
            }
        }
    ]
}