Errors

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]"
}

ErrorCode 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)

ErrorMessage 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

code	reason
`400#address.addressLine`	addressLine is required if address is present
`400#address.countryCode`	countryCode is required if address is present
`400#address.postalCode`	postalCode is required if address is present
`400#candidate?required-fields=address.city`	Candidate is missing required field for identity verification: address.city
`400#candidate?required-fields=address.addressLine`	Candidate is missing required field for identity verification: address.addressLine
`400#candidate?required-fields=address.state`	Candidate is missing required field for identity verification: address.state
`400#candidate?required-fields=address.zip`	Candidate is missing required field for identity verification: address.zip
`400#candidate?required-fields=dob`	Candidate is missing required field for identity verification: dob
`400#candidate?required-fields=dob`	Candidate is missing required field for package: dob
`400#candidate?required-fields=middleName`	Candidate 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

code	reason
`400#dob?format`	dob must be in the format of YYYY-MM-DD
`400#ssn?format`	ssn is not in the expected format
`400#phone?format`	phone is not in the expected format
`400#email?format`	email is not in the expected format
`400#address.regionCode?format`	regionCode format
`400#address.postalCode?format`	postalCode format
`400#address.countryCode?format`	countryCode format

Screening Errors

code	reason
`400#adverse-action-already-in-process`	An adverse action has already been initiated for this screening
`400#adverse-action?configuration`	Adverse Action has not been configured for this account
`400#report-status-not-ready`	Screening is not eligible for adverse action at this time
`400#reportItemIds?not-allowed`	This report does not allow you to include the reason for initiating Adverse Action. Please remove the reportItemId(s) and resubmit.
`409#clientReferenceId?already-in-use`	clientReferenceId already in use
`409#email?already-in-use`	email already in use
`400#identityId`	Trusted identifier already assigned to this candidate
`400#fileName`	fileName is required
`400#fileName`	fileName is required
`400#driversLicense.licenseNumber?format`	licenseNumber is not in the expected format
`400#driversLicense.issuingAgency?format`	issuingAgency is not in the expected format
`400#kba.answers?failed`	Too many incorrect answers
`400#kba.answers?invalid-selection`	Answer given for questionId {1-4} does not match any option
`400#candidate?required-fields=address.city`	Candidate {id} is missing required field for identity verification: address.city
`400#candidate?required-fields=address.addressLine`	Candidate {id} is missing required field for identity verification: address.addressLine
`400#candidate?required-fields=address.state`	Candidate {id} is missing required field for identity verification: address.state
`400#candidate?required-fields=address.postalCode`	Candidate {id} is missing required field for identity verification: address.postalCode
`422#identity?retry-limit-exceeded`	Retry limit exceeded
`400#candidateId?not-found`	candidateId must be a valid candidateId associated with the authenticated account
`400#kba.answers`	All kba questions must be answered
`400#candidateId?not-found`	candidateId must be a valid candidateId associated with the authenticated account
`400#packageId?not-found`	packageId must be an active packageId associated with the authenticated account
`400#trustedUserId?not-found`	trusted user must be a valid, active trusted user
`400#documentType`	documentType must be one of: [end-user-agreement, disclosure-and-authorization]
`400#party`	party must be one of: [candidate, trusted-user]
`400#candidateId?not-found`	candidateId must be a valid candidateId associated with the authenticated account
`400#ticketing`	Invalid value some-bad-value in field: ticketing
`400#documentType`	documentType must be one of: [end-user-agreement, disclosure-and-authorization]
`400#trustedUserId?not-found`	trusted user must be a valid, active trusted user
`400#party`	party must be one of: [candidate, trusted-user]
`400#schedule.startAt?format`	schedule.startAt must be a UTC time with date, hours, and minutes, like 2016-10-30T20:00:00.000Z
`400#candidate-and-package-already-subscribed`	A subscription already exists for this candidate and package
`400#schedule.endAt?format`	schedule.endAt must be a UTC time with date, hours, and minutes, like 2016-10-30T20:00:00.000Z
`400#candidate-and-package-already-subscribed`	A subscription already exists for this candidate and package
`400#candidate?required-fields=dob`	Candidate {id} is missing required field for package {id}: dob.
`400#candidate?required-fields=middleName`	Candidate {id} is missing required field for package {id}: middleName.
`400#identityId`	Trusted identifier already assigned to this candidate
`400#identityId`	identity id must belong to a verified identity