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

JSON

{
      "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:

JSON

{
      "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
409#clientReferenceId?already-in-use	clientReferenceId already in use
409#email?already-in-use	email already in use

Examples

Error Message

JSON

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

Solution

Include the "givenName" field in the candidate object:

JSON

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

Error Message

JSON

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

Solution

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

JSON

{
    //...
    "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
400#driversLicense.licenseNumber?format	licenseNumber is not in the expected format
400#driversLicense.issuingAgency?format	issuingAgency is not in the expected format
400#callback.uri?format	callback.uri must be a valid https url

Screening Errors

code	reason
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#documentType	documentType must be one of: [end-user-agreement, disclosure-and-authorization]
400#screening?required-data	Street address is required
400#screening?required-data	Package requires city of residence of candidate
400#screening?required-data	State is required
400#screening?required-data	Zipcode is required
400#screening?required-data	Package requires a valid date of birth of candidate
400#screening?required-data	No Employer data provided
400#screening?required-data	No Education data provided