GraphQL error responses

GraphQL error responses

GraphQL error responses

GraphQL error responses

Unlike REST APIs, GraphQL servers don’t use HTTP status codes to indicate unsuccessful requests. Instead, the GraphQL response body includes an array of errors when an operation fails.
The SEEK API uses four error codes to classify the type of error that occurred. Depending on the type of error there will be further information in the error’s message and extensions.
The SEEK API’s error messages are safe to expose to SEEK hirers. However, some errors responses can indicate a problem with your SEEK API integration that’s not actionable by an end user. If you decide to hide those error messages, your software should still log the full message to support debugging issues.

UNAUTHENTICATED

An UNAUTHENTICATED error indicates a problem with the access token included in the request. More details will be available in the error’s message.

Common causes

  • An access token wasn’t included in the request’s Authorization header.
  • The access token has expired. This can happen if the access token is used after the expires_in from the token response.
  • A Playground access token was used to access live data or vice versa.

Sample response

JSON
Copy
{
  "errors": [
    {
      "message": "Public test partner token is expired",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": ["candidateProfile"],
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ]
}

FORBIDDEN

A FORBIDDEN error indicates a valid access token was received but there was a problem authorising the operation. More details will be available in the error’s message.
It’s possible to have access to an object but not all of its nested objects or fields. For example, you can query a PositionProfile for application export but wouldn’t be able to query its branding without an additional job posting relationship. To help debugging these situations the error’s path will indicate which field encountered the FORBIDDEN error.

Common causes

Example failing query

QueryVariablesResult
Copy Playground
query ($id: String!) {
  # Hirer has been disabled
  hiringOrganization(id: $id) {
    name
  }
}

BAD_USER_INPUT

A BAD_USER_INPUT error indicates the operation failed input validation. A top-level summary of the validation failure will be available in the error’s message.
Some operations support additional field-level messages in the invalidFields map. Its keys are JSON Pointers to the invalid fields in the operation’s arguments. These map to a message describing why the field failed validation.

Common causes

  • The input was the correct type for the GraphQL schema but violated a more specific constraint.
  • A mutation’s input referenced an object that doesn’t exist.
  • The operation exceeded the SEEK API’s query complexity limit.
    An operation’s complexity is calculated based on the estimated size of its response. Overly complex operations are rejected before they’re executed to prevent denial of service attacks .

Example failing mutation

MutationVariablesResult
Copy Playground
mutation ($input: CreateWebhookSubscriptionInput!) {
  createWebhookSubscription(input: $input) {
    ... on CreateWebhookSubscriptionPayload_Success {
      webhookSubscription {
        id {
          value
        }
      }
    }


    ... on CreateWebhookSubscriptionPayload_Conflict {
      conflictingWebhookSubscription {
        id {
          value
        }
      }
    }
  }
}

INTERNAL_SERVER_ERROR

An INTERNAL_SERVER_ERROR indicates an unexpected failure occurred while processing the request.
Error details are omitted from the response to avoid exposing sensitive information about SEEK’s systems. However, the message will contain a reference code SEEK can use to find more details in our internal logs.

Sample response

JSON
Copy
{
  "errors": [
    {
      "message": "Oops. Something went wrong. If you continue to experience issues, contact support and quote error reference '112c-4edf-af8e'.",
      "path": ["positionProfile"],
      "extensions": {
        "code": "INTERNAL_SERVER_ERROR"
      }
    }
  ]
}
GraphQL: In practice
Auth: Overview
Auth: Overview