Troubleshoot GraphQL errors

Diagnose GraphQL errors returned by the API.

 

Overview

For OAuth errors that happen before a GraphQL call, see Troubleshoot OAuth errors.

For an introduction to GraphQL, see Apollo Odyssey: GraphQL Tutorials (opens in a new window) and Errors (opens in a new window) in the GraphQL specification.

Detect GraphQL errors

Check the HTTP status code and the errors array. A 200 response can still contain errors.

errors includes message, plus an optional extensions with a code and classification:

{
  "errors": [{
    "message": "Description of error",
    "path": ["Path"],
    "extensions": {
      "code": "BAD_USER_INPUT",
      "classification": {
        "type": "ExtendedValidationError",
        "validatedPath": [
          "patchEmployer",
          "input",
          "employerAttributes",
          "countrySpecificAttributes",
          0,
          "websiteUrl"
        ],
        "constraint": "@DossierUrlConstraint"
      },
      "serviceName": "company-data-api",
      "stacktrace": [
        "Stack trace"
      ]
    }
  }],
  "data": {
    "patchEmployer": null
  }
}

Detect GraphQL errors

Value	Description
errors.message	Describes the error. See Common GraphQL error messages. Example: "errors": [{ "message": "<message>", }]
errors.path	Where the error occurred. Example: "errors": [{ "message": "<message>", "path": ["patchEmployer"] }]
errors.extensions	Fields for debugging.
errors.extensions.code	Error code.
errors.extensions.code.validatedPath	Field that caused the error.
errors.extensions.code.constraint	Schema constraint that failed.
errors.extensions.classification	Details when a field constraint fails.

Common GraphQL error messages

When a GraphQL error occurs, errors describes what failed. Depending on the error, data can be partial, null, or absent. Common messages:

• Authorization Error
• Data Integrity or Validation Error
• Internal Error
• Internal server error
• JobIdentifierInput must specify one of indeedJobKey, employerJobId, or atsApplicationIdentifier
• JobSeekerIdentifierInput must specify either indeedJobSeekerKey or emailAddress
• PartnerDispositionIdentifierInput must specify one of indeedApplyID, ittk, universalApplyId, or alternateIdentifier
• Unable to parse statusChangeDateTime
• Validation errors in batch requests
• Variable input has an invalid value error

Authorization error

Authorization error

message	Authorization Error
Summary	Indeed monitors this error. Contact Indeed for details.

Data integrity or validation error

Data integrity or validation error

message	Data Integrity or Validation Error
Summary	The API could not process the input. Check the values. If the error continues, contact Indeed.

Internal error

Internal error

message	Internal Error
Summary	Indeed monitors this error. Contact Indeed Support for details.

Internal server error

A call can fail even when the service is up. The failure can be a back-end service, the network, or something between them.

Retry these errors. If a retry succeeds, the failure was temporary. If it continues, contact Indeed Support.

When you call the Indeed PLUS APIs, initiate a timeout after 5,000 milliseconds.

JobIdentifierInput must specify one of indeedJobKey, employerJobId, or atsApplicationIdentifier

JobIdentifierInput must specify one of indeedJobKey, employerJobId, or atsApplicationIdentifier

message	JobIdentifierInput must specify one of indeedJobKey, employerJobId, or atsApplicationIdentifier
Summary	Send at least one of these identifiers: indeedJobKey employerJobId atsApplicationIdentifier

JobSeekerIdentifierInput must specify either indeedJobSeekerKey or emailAddress

JobSeekerIdentifierInput must specify either indeedJobSeekerKey or emailAddress

message	JobSeekerIdentifierInput must specify either indeedJobSeekerKey or emailAddress
Summary	Send at least one of these identifiers: indeedJobSeekerKey emailAddress

PartnerDispositionIdentifierInput must specify one of indeedApplyID, ittk, universalApplyId, or alternateIdentifier

PartnerDispositionIdentifierInput must specify one of indeedApplyID, ittk, universalApplyId, or alternateIdentifier

message	PartnerDispositionIdentifierInput must specify one of indeedApplyID, ittk, universalApplyId, or alternateIdentifier
Summary	Send at least one of these identifiers: indeedApplyID ittk universalApplyId alternateIdentifier

Unable to parse statusChangeDateTime

Unable to parse statusChangeDateTime

message	Unable to parse statusChangeDateTime
Summary	Indeed received the request but could not parse statusChangeDateTime. Send a statusChangeDateTime that follows RFC 3339 (opens in a new window) and is not a future date.

Validation errors in batch requests

A batch can fail as a whole when one job fails. That follows how GraphQL works.

In a batch, sourcedPostingIds follow the order of the job postings you sent.

How the Job Sync API handles the error depends on classification:

Validation errors

Error classification	The Job Sync API
ExtendedValidationError	Keeps processing the other jobs in the batch.
Other than ExtendedValidationError	Rejects the whole batch when any job fails. For an example of this type of error, see Example validation error.

Example validation error

{
  "errors": [{
    "extensions": {
      "code": "BAD_USER_INPUT",
      "classification": "ValidationError"
    },
    "locations": [{
      "line": 1,
      "column": 46
    }],
    "message": "Validation error (WrongType@[jobsIngest/createSourcedJobPostings]) : argument 'input.jobPostings[1].metadata.contacts[0].contactInfo.contactPhone' with value 'StringValue{value='***********'}' is not a valid 'PhoneNumber' - String value `10001212223` is not a valid E.164 phone number"
  }]
}

Variable input has an invalid value error

Variable input has an invalid value error

message	Variable 'input' has an invalid value: String value is not a valid web URL. Relative paths are not allowed. Value must be an absolute URL.
code	BAD_USER_INPUT
Summary	When a variable fails validation, GraphQL names the variable and the reason. It does not include the path where the variable is used. Indeed validations add that path. GraphQL framework checks, such as type checks, do not.

Common GraphQL error codes

See also Built-in error codes (opens in a new window).

Common values of errors.extensions.code:

Common GraphQL error codes

Error	Description and common causes	Can unmodified query succeed?
BAD_REQUEST	Invalid input. See the error message.	No
BAD_USER_INPUT	Invalid input. Read the message, change the query, and retry. See BAD_USER_INPUT error.	No
FORBIDDEN	Valid credentials without permission for this operation. Same as HTTP 403 Forbidden. Also returned when the event does not exist, so do not use the response to enumerate accounts. See OWASP: Testing for User Enumeration and Guessable User Account (opens in a new window). Change the query and retry. See FORBIDDEN error.	No
GRAPHQL_PARSE_FAILED	See GRAPHQL_PARSE_FAILED error.
INTERNAL_SERVER_ERROR	Unexpected server error. Retry the request.	Yes
QUERY_TOO_COMPLEX	Query is too complex. Change it and retry.	No
QUERY_TOO_NESTED	Query is nested too deeply. Change it and retry.	No
UNAUTHENTICATED	Missing credentials. Same as HTTP 401 Unauthorized. See Integrate with Indeed and call APIs. Add credentials and retry.	No

BAD_USER_INPUT error

BAD_USER_INPUT error

message	Exception while fetching data
code	BAD_USER_INPUT
Summary	The request included invalid data.

This BAD_USER_INPUT example is an application-level input validation error:

{
  "errors": [{
    "message": "Exception while fetching data (/patchEmployer) : EmployerIdentifiersInput contains invalid type or id",
    "path": [
      "patchEmployer"
    ],
    "extensions": {
      "code": "BAD_USER_INPUT",
      "classification": {
        "type": "ExtendedValidationError",
        "validatedPath": [
          "patchEmployer",
          "input",
          "employerAttributes",
          "countrySpecificAttributes",
          0,
          "websiteUrl"
        ],
        "constraint": "@DossierUrlConstraint"
      },
      "serviceName": "company-data-api",
      "stacktrace": [
        "GraphQLError: Exception while fetching data (/patchEmployer) : EmployerIdentifiersInput contains invalid type or id"
      ]
    }
  }],
  "data": {
    "patchEmployer": null
  }
}

FORBIDDEN error

FORBIDDEN error

message	Client is not authorized
code	FORBIDDEN
Summary	The OAuth client is not registered with the Indeed API gateway.

You get Client is not authorized with FORBIDDEN when the OAuth client is not registered with the Indeed API gateway. For example:

{
  "data": null,
  "errors": [{
    "extensions": {
      "code": "FORBIDDEN"
    },
    "message": "Client is not authorized."
  }]
}

To register the client, contact Support (opens in a new window).

GRAPHQL_PARSE_FAILED error

GRAPHQL_PARSE_FAILED error

message	Syntax Error: Invalid number, expected digit but got: "a".
code	GRAPHQL_PARSE_FAILED
Summary	The operation has a syntax error. This usually means HTML in description is not escaped.

This payload leaves the HTML unescaped:

mutation {
  createSourcedJobPostings(
    input: {
      jobPostings: [{
        body: {
          title: "Server"
          description: "<h4 style="text - align: left;">Responsibilities include:</h4>
          <ul>
            <li style="text-align: left;"> Customer interaction </li>
            <li style="text-align: left;"> Taking orders and closing checks </li>
            <li style="text-align: left;"> Food and drink service </li>
            <li style="text-align: left;"> General table and restaurant maintenance </li>
            <li style="text-align: left;"> Restaurant opening and closing duties </li>
          </ul>"
          location: {
            country: "US",
            cityRegionPostal: "Clio, MI 48420"
          }
          benefits: []
          salary: {
            currency: "USD"
            minimumMinor: 387
            maximumMinor: 387
            period: "HOUR"
          }
        }
        metadata: {
          jobSource: {
            companyName: "Company name"
            sourceName: "Parent company name"
            sourceType: "Employer"
          }
          contacts: {
            contactType: "contact"
            contactInfo: {
              contactName: "Contact name"
              contactEmail: "contact@email.com"
            }
          }
          jobPostingId: "7308"
          datePublished: "2023-09-13T17:32Z"
          url: "https://companyname.com/jobs/1000/server"
        }
        applyMethod: {
          indeedApply: {
            apiToken: "e03dd8c2dd1748218c6d5cde83824606807f617dfa054b78f9192d1341a5d15d"
            postUrl: "https://app.companyname.com/ext/indeed/apply/"
            applyQuestions: "https://app.companyname.com/ext/indeed/apply/questions/1000/"
            resumeRequired: YES
            phoneRequired: YES
          }
        }
      }]
    }
  ) {
    results {
      jobPosting {
        sourcedPostingId
      }
    }
  }
}

The API returns:

{
  'errors': [{
    'message': 'Syntax Error: Invalid number, expected digit but got: "a".',
    'locations': [{
      'line': 7,
      'column': 33
    }],
    'extensions': {
      'code': 'GRAPHQL_PARSE_FAILED'
    }
  }]
}

Escape the quotes in description. Tags such as <h4>, <ul>, and <li> can stay as they are:

mutation {
  createSourcedJobPostings(
    input: {
      jobPostings: [{
        body: {
          title: "Server"
          description: "<h4 style=\"text - align: left;\">Responsibilities include:</h4>
          <ul>
            <li style=\"text-align: left;\"> Customer interaction </li>
            <li style=\"text-align: left;\"> Taking orders and closing checks </li>
            <li style=\"text-align: left;\"> Food and drink service </li>
            <li style=\"text-align: left;\"> General table and restaurant maintenance </li>
            <li style=\"text-align: left;\"> Restaurant opening and closing duties </li>
          </ul>"
          location: {
            country: "US",
            cityRegionPostal: "Clio, MI 48420"
          }
          benefits: []
          salary: {
            currency: "USD"
            minimumMinor: 387
            maximumMinor: 387
            period: "HOUR"
          }
        }
        metadata: {
          jobSource: {
            companyName: "Company name"
            sourceName: "Parent company name"
            sourceType: "Employer"
          }
          contacts: {
            contactType: "contact"
            contactInfo: {
              contactName: "Contact name"
              contactEmail: "contact@email.com"
            }
          }
          jobPostingId: "7308"
          datePublished: "2023-09-13T17:32Z"
          url: "https://companyname.com/jobs/1000/server"
        }
        applyMethod: {
          indeedApply: {
            apiToken: "e03dd8c2dd1748218c6d5cde83824606807f617dfa054b78f9192d1341a5d15d"
            postUrl: "https://app.companyname.com/ext/indeed/apply/"
            applyQuestions: "https://app.companyname.com/ext/indeed/apply/questions/1000/"
            resumeRequired: YES
            phoneRequired: YES
          }
        }
      }]
    }
  ) {
    results {
      jobPosting {
        sourcedPostingId
      }
    }
  }
}

HTTP status codes

GraphQL calls can return these HTTP status codes:

GraphQL-related HTTP status codes

HTTP status code	Description and resolution
200 without an errors array	The GraphQL operation succeeded.
200 with an errors array	An error occurred.
400	The server could not parse the request as a GraphQL document or validate it against the schema. The same status is returned for other request problems, such as a batched HTTP request when allowBatchedHttpRequests is off, or a request blocked by CSRF prevention.
405	The HTTP method is not valid. Examples: GET with a mutation, or a method other than GET or POST.
429	You sent too many requests in the time window. Wait before you send another request, or lower your overall request rate. Retries can add to the request count. See: Rate limiting Job Sync API guide -> Rate limits 429 Too Many Requests (opens in a new window)
500	The server did not start, or it is shutting down. Your context function threw an error. Processing failed unexpectedly. A server bug or a plugin hook error can cause this.

HTTP status codes are defined in RFC 9110: Overview of Status Codes (opens in a new window).

Apollo Server error codes are in Apollo GraphQL Docs: Setting HTTP status code and headers (opens in a new window).

See also

• Common GraphQL error codes
• Built-in error codes (opens in a new window)

 

Was this page helpful?