Overview

Sterling uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate a success, codes in the 4xx range indicate a request that failed given the information provided (e.g. a required parameter was omitted, format issues, etc.), and codes in the 5xx range indicate an error with Sterling's servers.

When a request is valid but does not complete successfully, we return a 400# error code. Below you'll find more detailed information about the possible errors you can expect.

Error Format

The expected format for an error is as follows:

📘

Error Format

{
      "code": "400#[optional-object]?[optional-reason]",
      "message": "[optional-message]"
}

Error Code Format

  • Example: 400#dob?format
  • HTTP error code (i.e. 400#)
  • Offending field when relevant (e.g. dob)
  • Brief message when applicable (e.g. format or required)

Error Message Format

  • The error message provides more context as to why the error occurred (e.g. "message": "dob must be in the format of YYYY-MM-DD")

Example:

{
      "code": "400#dob?format",
      "message": "dob must be in the format of YYYY-MM-DD"
}

🚧

Since the error message can change from time to time, we highly recommend you key off of the error code if you plan implement any automation for errors.

Candidate Validation Errors

Required Fields

codereason
400#address.addressLineaddressLine is required if address is present
400#address.countryCodecountryCode is required if address is present
400#address.postalCodepostalCode is required if address is present
400#candidate?required-fields=address.cityCandidate is missing required field for identity verification: address.city
400#candidate?required-fields=address.addressLineCandidate is missing required field for identity verification: address.addressLine
400#candidate?required-fields=address.stateCandidate is missing required field for identity verification: address.state
400#candidate?required-fields=address.zipCandidate is missing required field for identity verification: address.zip
400#candidate?required-fields=dobCandidate is missing required field for identity verification: dob
400#candidate?required-fields=dobCandidate is missing required field for package: dob
400#candidate?required-fields=middleNameCandidate is missing required field for package: middleName (or confirmedNoMiddleName set to true)

Examples

Error Message

{
  "errors": [
    {
      "code": "400#givenName",
      "message": "givenName is required"
    }
  ]
}

Solution

Include the "givenName" field in the candidate object:

{
    //...
    "givenName": "John",
    //...
}

Error Message

{
  "errors": [
    {
      "code": "400#address.addressLine",
      "message": "if address is provided, addressLine is required"
    }
  ]
}
Solution

In the "address" sub-object, include a "addressLine" field:

{
    //...
    "givenName": "John",
    //..
    "address": {
         "addressLine": "123 Example Street",
         "municipality": "ATLANTA",
         //..
     }
}

Format Validation Errors

codereason
400#dob?formatdob must be in the format of YYYY-MM-DD
400#ssn?formatssn is not in the expected format
400#phone?formatphone is not in the expected format
400#email?formatemail is not in the expected format
400#address.regionCode?formatregionCode format
400#address.postalCode?formatpostalCode format
400#address.countryCode?formatcountryCode format

Screening Errors

codereason
400#adverse-action-already-in-processAn adverse action has already been initiated for this screening
400#adverse-action?configurationAdverse Action has not been configured for this account
400#report-status-not-readyScreening is not eligible for adverse action at this time
400#reportItemIds?not-allowedThis report does not allow you to include the reason for initiating Adverse Action. Please remove the reportItemId(s) and resubmit.
409#clientReferenceId?already-in-useclientReferenceId already in use
409#email?already-in-useemail already in use
400#identityIdTrusted identifier already assigned to this candidate
400#fileNamefileName is required
400#fileNamefileName is required
400#driversLicense.licenseNumber?formatlicenseNumber is not in the expected format
400#driversLicense.issuingAgency?formatissuingAgency is not in the expected format
400#kba.answers?failedToo many incorrect answers
400#kba.answers?invalid-selectionAnswer given for questionId {1-4} does not match any option
400#candidate?required-fields=address.cityCandidate {id} is missing required field for identity verification: address.city
400#candidate?required-fields=address.addressLineCandidate {id} is missing required field for identity verification: address.addressLine
400#candidate?required-fields=address.stateCandidate {id} is missing required field for identity verification: address.state
400#candidate?required-fields=address.postalCodeCandidate {id} is missing required field for identity verification: address.postalCode
422#identity?retry-limit-exceededRetry limit exceeded
400#candidateId?not-foundcandidateId must be a valid candidateId associated with the authenticated account
400#kba.answersAll kba questions must be answered
400#candidateId?not-foundcandidateId must be a valid candidateId associated with the authenticated account
400#packageId?not-foundpackageId must be an active packageId associated with the authenticated account
400#trustedUserId?not-foundtrusted user must be a valid, active trusted user
400#documentTypedocumentType must be one of: [end-user-agreement, disclosure-and-authorization]
400#partyparty must be one of: [candidate, trusted-user]
400#candidateId?not-foundcandidateId must be a valid candidateId associated with the authenticated account
400#ticketingInvalid value some-bad-value in field: ticketing
400#documentTypedocumentType must be one of: [end-user-agreement, disclosure-and-authorization]
400#trustedUserId?not-foundtrusted user must be a valid, active trusted user
400#partyparty must be one of: [candidate, trusted-user]
400#schedule.startAt?formatschedule.startAt must be a UTC time with date, hours, and minutes, like 2016-10-30T20:00:00.000Z
400#candidate-and-package-already-subscribedA subscription already exists for this candidate and package
400#schedule.endAt?formatschedule.endAt must be a UTC time with date, hours, and minutes, like 2016-10-30T20:00:00.000Z
400#candidate-and-package-already-subscribedA subscription already exists for this candidate and package
400#candidate?required-fields=dobCandidate {id} is missing required field for package {id}: dob.
400#candidate?required-fields=middleNameCandidate {id} is missing required field for package {id}: middleName.
400#identityIdTrusted identifier already assigned to this candidate
400#identityIdidentity id must belong to a verified identity