REST HTTP Errors
The current version of the SheerID REST API (0.5) may return a non-2XX HTTP status code if an unexpected condition occurs.
Convention
REST API resource methods that are invoked with sensible request parameters generally return a 200 OK HTTP status in conjunction with the documented response body (e.g. a JSON-serialized object literal or array — check the resource documentation’s “Expected Response” section for resource-specific details), or a 204 No Content HTTP status if the resource method does not return any content.
Some REST resource methods may return a 3XX redirect to another resource, such as the canonical URL for a resource that is accessed via a friendly URL
4XX status codes, such as 400 Bad Request, 401 Unauthorized and 404 Not Found are used to indicate user error. The user (API integrator or end-user) may be able to recover from this error by doing something to correct the request, whether it be fixing a data issue, supplying the correct URL or authenticating with valid credentials, for example.
5XX status codes, such as 500 Unexpected Server Error are used to indicate a service error. The only recourse the integrator may have for dealing with this type of error is resubmit the request after a period of time (instantly if there is an intermittent issue), or contact SheerID support for more information. Needless to say, this type of error is prevented whenever possible.
Usage
Upon receiving a response from a REST API resource, integrators should first ensure that the response HTTP status code matches the expected status. Any REST resource method that does not return a 200 OK HTTP status code as its primary expected HTTP status code (example: Revoke Token) will explicitly state the expected HTTP response status in the “Expected Response” section. If the HTTP status code does not match the expected response, the API client should not expect the full response payload as described in “Expected Response”, but rather a minimal, JSON-serialized error payload containing the following properties:
| Property Name | Included? | Description |
|---|---|---|
httpStatus |
Always | The HTTP status code (this will always match the status code returned in the HTTP response headers) |
message |
Sometimes | A human-readable (English) error message providing additional detail as to the nature of the error. |
errorCode |
Sometimes | A machine-readable (numeric) code from the list of SheerID REST API Error Codes providing additional detail as to the nature of the error. |
status |
Always |
This property will be removed in a future API version. Please refer to
httpStatus instead.A string representation of the HTTP status code (this will always match the status code returned in the HTTP response headers). |
Resource methods that may return a non-2XX HTTP status for expected error conditions will list the potential HTTP status codes in the resource method documentation, under the “Errors (HTTP Status Codes)” section.
Examples
Email address is not a valid format
To ensure we have a valid method of contacting users as is necessary to communicate the status of a verification request, any request that contains an email address is validated to ensure the email address looks valid according to email address formatting rules. Requests with invalid email addresses are rejected with a 400 Bad Request status code.
Request (curl)
curl -H "Authorization: Bearer $TOKEN" https://services-sandbox.sheerid.com/rest/0.5/verification -d organizationId=323 -d FIRST_NAME=Joe -d LAST_NAME=Test -d BIRTH_DATE=1992-12-05 -d EMAIL=malformed
Response (with headers)
HTTP/1.1 400 Bad Request {"message":"Invalid email address format.","httpStatus":400,"status":"400","errorCode":1002}
Birth date indicates a person is under 13 years of age
In order to protect the privacy of children online, SheerID does not accept data from individuals younger than 13 years of age. As a result, verification attempts containing a birth date which indicates the individual is below this age will be rejected with a 400 Bad Request status code.
Request (curl)
curl -H "Authorization: Bearer $TOKEN" https://services-sandbox.sheerid.com/rest/0.5/verification -d organizationId=323 -d FIRST_NAME=Joe -d LAST_NAME=Test -d BIRTH_DATE=2002-12-05
Response (with headers)
HTTP/1.1 400 Bad Request {"message":"Person is ineligible for verification because of age.","httpStatus":400,"status":"400","errorCode":1013}
Date value does not match the expected format
Unless otherwise specified, date values are expected to be in YYYY-MM-DD format (Example: 1969-12-28 represents December 28, 1969). Verification requests submitted with a value for a date field such as BIRTH_DATE or STATUS_START_DATE that deviates from this format will be rejected with a 400 Bad Request status code.
Request (curl)
curl -H "Authorization: Bearer $TOKEN" https://services-sandbox.sheerid.com/rest/0.5/verification -d organizationId=323 -d FIRST_NAME=Joe -d LAST_NAME=Test -d BIRTH_DATE=12/5/95
Response (with headers)
HTTP/1.1 400 Bad Request {"message":"Invalid date format.","httpStatus":400,"status":"400","errorCode":1001}
References
Please refer to the complete list of Status Code Definitions published with the HTTP/1.1 protocol spec. The HTTP status codes returned by the SheerID REST API attempt to adhere to the HTTP specifications as much as is reasonably possible.