# Handling Errors

## 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](/graphql-api/api-reference/objects/model-validation-error.md) object.

Here is an example response for an [`updateAddressDetails`](/graphql-api/api-reference/objects/update-address-details-payload.md) mutation.

{% code title="GraphQL mutation" %}

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

{% endcode %}

{% hint style="info" %}
Note that you need to include `errors` field in the query to retrieve the validation errors.
{% endhint %}

{% code title="GraphQL Variables" %}

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

{% endcode %}

{% code title="Response" %}

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

{% endcode %}

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`

{% code title="GraphQL mutation" %}

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

{% endcode %}

{% code title="GraphQL variables" %}

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

{% endcode %}

{% code title="GraphQL response" %}

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

{% endcode %}

{% hint style="info" %}
Note that the `errors` field is in the root of the object and not under `data.updateOrderedProductQuantity.`
{% endhint %}

## 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`.

{% code title="GraphQL query" %}

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

{% endcode %}

{% code title="GraphQL response" %}

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

{% endcode %}

## 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:

```json
{
    "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"
            }
        }
    ]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.firmhouse.com/graphql-api/handling-errors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.