Errors

When everything works as expected there are no errors returned from the server, and just the data you requested. Unfortunately, errors do happen. Sometimes because you formatted data request incorrectly and sometimes because something bad happened on the server.

Queries

A query might result in some data and some errors, and those should be returned in a JSON object of the form:

{
  "data": { ... },
  "errors": [ ... ]
}

If there were no errors returned, the errors field should not be present on the response.

If an error is thrown while resolving a field, the field returns null and an error is be added to the errors list in the response.

An error object includes an extensions object which contains additional information. Its code captures the type of problem, and id is a unique identifier that can be given to Wave Support to assist in an investigation.

See GraphQL Specification 7.1.2 Errors for more information.

Example: Malformed Query

The server fails to validate the query as business does not accept an argument named name.

Operation

query {
  business(name: "Personal") {
    id
  }
}

Response

{
  "errors": [
    {
      "extensions": {
        "id": "e486c5f4-49b0-456f-897c-6d21bdabcde7",
        "code": "GRAPHQL_VALIDATION_FAILED"
      },
      "message": "Unknown argument \"name\" on field \"business\" of type \"Query\".",
      "locations": [
        {
          "line": 2,
          "column": 12
        }
      ]
    }
  ]
}

Example: Resource Not Found

The server cannot find a Business with an id of BAD_ID.

Operation

query {
  business(id: "BAD_ID") {
    id
    name
  }
}

Response

{
  "errors": [
    {
      "extensions": {
        "id": "d9e441c5-8c54-421b-bcdb-f0c2012a9f9c",
        "code": "NOT_FOUND"
      },
      "message": "Business 'BAD_ID' could not be found.",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "business"
      ]
    }
  ],
  "data": {
    "business": null
  }
}

Example: Login Required

Authorization header missing or token is expired.

Operation

query {
  user {
    id
    defaultEmail
  }
}

Response

{
  "errors": [
    {
      "extensions": {
        "id": "d9e441c5-8c54-421b-bcdb-f0c2012a9f9c",
        "code": "UNAUTHENTICATED"
      },
      "message": "Login required.",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "user"
      ]
    }
  ],
  "data": {
    "user": null
  }
}

Example: Execution Error

These are requests that are properly formatted and are processed by Wave servers, but something bad and unexpected happened. These should be very rare but they do happen and need to be accounted for.

Operation

query {
  user {
    id
    defaultEmail
  }
}

Response

{
  "errors": [
    {
      "extensions": {
        "id": "d9e441c5-8c54-421b-bcdb-f0c2012a9f9c",
        "code": "INTERNAL_SERVER_ERROR"
      },
      "message": "Unknown error.",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "user"
      ]
    }
  ],
  "data": {
    "user": null
  }
}

Mutations

Mutations can have errors in two different ways:

1. Similar to queries, the response can include a list of GraphQL errors.
2. Input validation errors returned as inputErrors in the mutation's data response.

Example: Required Field

GraphQL error as requested operation does not match schema requirement, name is expected.

Operation

mutation {
  customerCreate(input: {
    businessId: "<BUSINESS_ID>"
  }) {
    didSucceed
    inputErrors {
      code
      message
      path
    }
    customer {
      id
      name
    }
  }
}

Response

{
  "errors": [
    {
      "extensions": {
        "id": "f99c027d-73ea-4ea7-8583-adfae6a65485",
        "code": "GRAPHQL_VALIDATION_FAILED"
      },
      "message": "Argument \"input\" has invalid value {businessId: \"<BUSINESS_ID>\"}.",
      "locations": [
        {
          "line": 2,
          "column": 25
        }
      ]
    },
    {
      "extensions": {
        "id": "d5935ecf-d045-40b0-bc30-62bd2565e671",
        "code": "GRAPHQL_VALIDATION_FAILED"
      },
      "message": "Field CustomerCreateInput.name of required type String! was not provided.",
      "locations": [
        {
          "line": 2,
          "column": 25
        }
      ]
    }
  ]
}

Example: Missing Value

Input validation error as content meets schema requirements but name requires a value.

Operation

mutation ($name: String!) {
  customerCreate(input: {
    businessId: "<BUSINESS_ID>",
    name: $name
  }) {
    didSucceed
    inputErrors {
      code
      message
      path
    }
    customer {
      id
      name
    }
  }
}

Operation Variables

{
  "name": ""
}

Response

{
  "data": {
    "customerCreate": {
      "didSucceed": false,
      "inputErrors": [
        {
          "code": "REQUIRED",
          "message": "This field is required.",
          "path": [
            "input",
            "name"
          ]
        }
      ],
      "customer": null
    }
  }
}