Error Handling

There are several error types in the GraphQL API and you may come across different ones depending on the operations you are trying to perform.

The Nautical GraphQL API handles the following three types of errors.

Query-level errors

This error occurs if, while performing some specified operation, you provide wrong or unrecognized input data. The GraphQL checks the syntax as you write and, if you are trying to perform an unknown operation, you will be notified by the editor you are using. If you proceed with sending the request, you will get a syntax error.

Below is an example of an error triggered by the wrong syntax. The following query tries to fetch the fullName field which doesn't exist on the User type:

{
  me {
    fullName
  }
}

Sending this query to the server would result in the following syntax error:

{
  "error": {
    "errors": [
      {
        "message": "Cannot query field \"fullName\" on type \"User\". Did you mean \"firstName\" or \"lastName\"?",
        "locations": [
          {
            "line": 3,
            "column": 5
          }
        ]
      }
    ]
  }
}

Data-level errors

This type of error occurs when the user passes invalid data as the mutation input. For example, while creating a new user, you provide an email address that is already being used in another user's account. It is therefore not unique and, as a result, you will get a validation error.

Validation errors are part of the schema, which means that we need to include them in the query to get them explicitly. For example, in all mutations, they can be obtained through the errors field.

Below is an example of an error triggered by validation issues:

mutation {
  accountRegister(
    input: {
      email: "customer@example.com"
      password: ""
      redirectUrl: "http://dev.nauticalcommerce.com/reset-password/"
    }
  ) {
    user {
      email
    }
    accountErrors {
      field
      code
    }
  }
}

Validation errors are returned in a dedicated error field inside mutation results:

{
  "data": {
    "accountRegister": {
      "user": null,
      "accountErrors": [
        {
          "field": "email",
          "code": "UNIQUE"
        }
      ]
    }
  }
}

caution

Although all error types contain a message field, the returned message is only meant for debugging and is not suitable for display to your customers. Please use the code field and provide your own meaningful error messages.

Permission errors

This type of error occurs when you are trying to perform a specific operation but you are not authorized to do so; in other words, you have no sufficient permissions assigned.

Below is an example of an error triggered by insufficient authorization. The staffUsers query requires appropriate admin permissions:

{
  staffUsers(first: 20) {
    edges {
      node {
        id
      }
    }
  }
}

Executing it without proper permission would result in the following error:

{
  "errors": [
    {
      "message": "You do not have permission to perform this action",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": ["staffUsers"]
    }
  ],
  "data": {
    "staffUsers": null
  }
}