Error handling

Querying for errors

When calling a query or mutation, things might go wrong. The input might be invalid, the action you want to perform is invalid for the current state et cetera.

GraphQL allows codifying possible errors in the schema, so you can see in advance what errors to expect. You can query these errors in your queries and mutations, using a so-called inline fragment: ... on Type.

For example, the addCompany mutation has several outcomes:

AddCompanySuccess
ChamberOfCommerceNumberNotResolvedError
UnexpectedError

Add these to your query:

mutation AddCompany {
    addCompany(
        input: {
            chamberOfCommerceNumber: "63204258"
            name: "Beequip"
            street: "Willemskade"
            houseNumber: "18"
            postalCode: "3016 DL"
            city: "Rotterdam"
            telephoneNumber: "010 340 0844"
            website: "https://beequip.com"
        }
    ) {
        __typename
        ... on AddCompanySuccess {
            company {
                id
                name
                url
            }
        }
        ... on ChamberOfCommerceNumberNotResolvedError {
            message
        }
        ... on UnexpectedError {
            message
        }
    }
}

Notice the __typename field. This lets you distinguish between errors and a successful result. When the mutation fails due to a ChamberOfCommerceNumberNotResolvedError, you can see that in the results:

{
    "data": {
        "addCompany": {
            "__typename": "ChamberOfCommerceNumberNotResolvedError",
            "message": "The given Chamber of Commerce number could not be resolved. Perhaps it is invalid or does not belong to an existing Chamber of Commerce registration."
        }
    }
}

You can use this in your client code to handle each error differently.

Similarly, the inline fragment lets you check if the result was successful:

{
    "data": {
        "addCompany": {
            "__typename": "AddCompanySuccess",
            "company": {
                "id": "1",
                "name": "Beequip",
                "url": "https://beequip.com/marktplaats/companies/1-beequip/"
            }
        }
    }
}

One optimization you can use is to query the common interface Error instead of each error individually:

mutation AddCompany {
    addCompany(
        input: {
            chamberOfCommerceNumber: "63204258"
            name: "Beequip"
            street: "Willemskade"
            houseNumber: "18"
            postalCode: "3016 DL"
            city: "Rotterdam"
            telephoneNumber: "010 340 0844"
            website: "https://beequip.com"
        }
    ) {
        __typename
        ... on AddCompanySuccess {
            company {
                id
                name
                url
            }
        }
        ... on Error {
            message
        }
    }
}

Validation errors

You might receive a ValidationError when executing a mutation:

mutation AddCompany {
	addCompany(
		input: {
            // ...
		}
	) {
		... on AddCompanySuccess {
			company {
				id
				url
			}
		}
		... on Error {
			message
			__typename
		}
	}
}

{
    "data": {
        "addCompany": {
            "message": "Some fields contain invalid data. Query the ValidationError type for more specific error messages. Go to https://developer.beequip.nl/marketplace/guides/error-handling#validation-errors to see how to do this.",
            "__typename": "ValidationError"
        }
    }
}

This means one or more fields in your mutation contain invalid data, for example if a string is too long. If you query the ValidationError type specifically, you can see what is wrong with these fields:

mutation AddCompany {
	addCompany(
		input: {
            // ...
		}
	) {
		... on AddCompanySuccess {
			company {
				id
				url
			}
		}
		... on Error {
			message
			__typename
		}
        ... on ValidationError {
			fieldErrors {
				message
				path
			}
		}
	}
}

This returns a message per field, and the field path inside the input:

{
    "data": {
        "addCompany": {
            "message": "Some fields contain invalid data. Query the ValidationError type for more specified error messages. Go to https://developer.beequip.nl/marketplace/guides/error-handling#validation-errors to see how to do this.",
            "__typename": "ValidationError",
            "fieldErrors": [
                {
                    "message": "The company name should not exceed a length of 50 characters.",
                    "path": ["input", "name"]
                }
            ]
        }
    }
}

Adding an object Pagination