GraphQL error handling

A GraphQL query or mutation may result in an error response. This page explains what those errors mean.

Query errors

Query errors are typically returned inside the QueryError objects. For example:

1
2
query getWorkspace($workspaceAri: ID!) {
  shepherd {
    workspace(id: $workspaceAri) {
      ... on QueryError {
        message
        extensions {
          errorType
          ... on ShepherdGenericQueryErrorExtension {
            statusCode
            type
          }
        }
      }
    }
  }
}

Sample response:

1
2
{
  "data": {
    "shepherd": {
      "workspace": {
        "__typename": "QueryError",
        "message": "Workspace with id '84d8e33f-139b-4ca4-b5cd-586a5d858a2f' not found or not enabled",
        "extensions": [
          {
            "errorType": "NO_PRODUCT_ACCESS",
            "statusCode": 403,
            "type": "NO_PRODUCT_ACCESS"
          }
        ]
      }
    }
  }
}

Mutation errors

Mutation errors are typically found in mutation payload objects. For example:

1
2
mutation updateAlert($alertAri: ID!, $status: ShepherdAlertStatus) {
  shepherd {
    updateAlert(id: $alertAri, input:{ status: $status }) {
      success
      node {
        id
        title
        status
      }
      errors {
        message
        extensions {
          ... on ShepherdGenericMutationErrorExtension {
            statusCode
            type
          }
        }
      }
    }
  }
}

Sample response:

1
2
{
  "data": {
    "shepherd": {
      "updateAlert": {
        "success": false,
        "node": null,
        "errors": [
          {
            "message": "alert 67f59a35802a76b6d5911a732 not found",
            "extensions": {
              "statusCode": 400,
              "type": "BAD_REQUEST"
            }
          }
        ]
      }
    }
  }
}

GraphQL errors

An invalid query or mutation will also result in a payload containing the error, but in a slightly different format:

1
2
{
  "errors": [
    {
      "message": "Variable 'status' has an invalid value: Invalid input for enum 'ShepherdAlertStatus'. No value found for name 'IN_PROGRESS2'",
      "locations": [
        {
          "column": 32,
          "line": 1
        }
      ],
      "extensions": {
        "classification": "ValidationError",
        "errorSource": "GRAPHQL_GATEWAY",
        "statusCode": 400
      }
    }
  ]
}

Guard Detect error types

Guard Detect returns the following error types to indicate specific problems: