GraphQL error responses

GraphQL error responses

GraphQL error responses

GraphQL error responses

Unlike REST APIs, GraphQL servers respond with HTTP 200 OK even for unsuccessful requests. Instead, the GraphQL response 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.

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.
The SEEK API authorises operations based on a set of relationships between you and your SEEK hirers. Each use case requires a separate relationship to allow you to act on behalf of the hirer. SEEK’s support team must explicitly configure these relationships as part of onboarding a SEEK hirer to your software.
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

  • SEEK has not configured a relationship between you and the SEEK hirer.
  • The SEEK hirer’s account has been disabled.
  • You attempted to use a job posting feature for a SEEK hirer under credit hold.
  • A browser token was used without the scope required for the operation.
  • You used a mutation against Playground data.
    The Playground returns FORBIDDEN errors after validating the mutation’s input. You can use this feature to test input validation in the GraphQL Playground.

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 input failed a scheme-specific requirement.

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