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
orrequired
)
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 errorcode
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
{
"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 |
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 |