Errors

Learn about our response and error codes.

ComplyCube uses standard HTTP response codes to indicate the success or failure of an API request.
Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with ComplyCube's servers.
Some 4xx errors include an error code that briefly explains why the error occurred.
HTTP Response Codes
Code
Description
200 
Everything worked as expected.
204
The resource is deleted.
400
The request has missing arguments or is malformed. See examples of these types of errors.
401
The request is not authenticated.
402
The request is not available as payment is due. This is only returned for users on our credit-based plans.
403
The request is authenticated but does not have sufficient permissions.
404
The resource requested does not exist.
413
The request is too large.
422
A processing error has occurred.
429
The rate limit or service quota has been breached.
500
Something is wrong on our end. Subscribe to our status page to be notified of any incident.
Processing Errors
Error
Description
two_sides_expected
Returned when only one side of a supported document type is provided before running a check.
​
Applies to Document Check.
unsupported_document_format
Returned when an unsupported document attachment format is provided before running a check.
​
Applies to Document Check.
unsupported_document_type_country
Returned when a check is run against an unsupported ID type and country combination.
 
Applies to Document Check.
document_requires_issuing_country
Returned when a check is run against a document with a missing issuingCountry attribute.
​
Applies to Document Check.
document_type_undetected
Returned when an unsupported document type is checked. It could also be returned when the image quality is inadequate to recognize the document.
​
Applies to Document Check and eligible Document uploads.
invalid_check_update
Returned when an update request is made on an unmodifiable check type.

Only Standard Screening Checks and Extensive Screening Checks can be updated.
pending_check_unmodifiable
Returned when an update request is made on a check with a status of 'pending'.
image_unreadable
Returned when ComplyCube is not able to read data from a document image. This may occur when the image is of low quality or is incorrectly oriented.
​
Applies to Document Check and eligible Document uploads.
under_exposure
Returned when the uploaded document image is too dark. This may occur when the image is underexposed.
​
Applies to eligible Document uploads.
excessive_glare
Returned when the uploaded document image has excessive glare.
​
Applies to eligible Document uploads.
document_liveness_failed
Returned when a document photo is deemed likely as spoofed, i.e., not live. It could also be returned when the image quality is inadequate to establish the liveness.
​
Applies to eligible Document uploads.
document_photocopy_detected
Returned when a document photo is deemed to be a photocopy.
​
Applies to eligible Document uploads.
invalid_image_format
Returned when an invalid image format is provided.

Applies to Live Photo, Identity Check, and Document Check.
liveness_failed
Returned when a live photo is deemed likely as spoofed, i.e., not live. It could also be returned when the image quality is inadequate to establish the liveness.
​
Applies to Live Photo.
multiple_faces_detected
Returned when multiple faces are detected. The client must retake the live photo.
​
Applies to Live Photo.
no_face_detected
Returned when no faces are detected. The client must retake the live photo.
​
Applies to Live Photo.
face_not_centred
Returned when a face is not centered. The client must retake the live photo.
​
Applies to Live Photo.
facial_features_obstructed
Returned when facial features are obstructed. The client must retake the live photo.
​
Applies to Live Photo.
face_too_small
Returned when the face is too small. The client must come closer and retake the live photo.
​
Applies to Live Photo.
face_too_close
Returned when the face is too close. The client must move away from the camera and retake the live photo.
​
Applies to Live Photo.
face_not_centered
Returned when the face is too close to the edge of the photo. The client must center their face and retake the live photo.
​
Applies to Live Photo.
face_cropped
Returned when the face has been cropped. The client must retake the photo with their entire face in the frame.
​
Applies to Live Photo.
unsupported_poa_document_type
Returned when a check is run against an unsupported proof of address document.
 
Applies to Proof of Address Check.
unsupported_country
Returned when a check is run against an unsupported country.
 
Applies to Multi-Bureau Check.
missing_address_attributes
Returned when a check is run while lacking the minimum required address attributes.
 
Applies to Multi-Bureau Check.
missing_client_attributes
Returned when a check is run while lacking the minimum required client attributes.
 
Applies to Multi-Bureau Check.
invalid_id_number_format
Returned when a check is run with an incorrectly formatted ID Number for a given country (e.g., SSN, Social Insurance Number).
 
Applies to Multi-Bureau Check.
image_too_large
Returned when the image provided is too large.
​
Applies to Document, Live Photo, Identity Check, and Document Check.
Example of Standard Errors
Below, you will find some example error responses from the ComplyCube API.
Forbidden
You'll most likely receive a 401: Unauthorized response when you provide an invalid API key.
{
    "type": "unauthorized",
    "message": "The 'Authorization' header is invalid"
}
Bad Request
You'll get a 400: Bad Request when you fail validation.
{
    "type": "invalid_request",
    "message": "'personDetails' must be provided when client type is `person`",
    "param": "personDetails"
}
Not Found
When a resource is not found, you will get a 404: Not Found response.
{
    "type": "resource_not_found",
    "message": "Invalid client id '123456789'"
}
Rate Limited
You will receive a 429: Too Many Requests response when you make too many requests.
{
  "type": "rate_limit_exceeded",
  "message": "You have exceeded the rate limit prescribed to your plan"
}
Internal Server Error
You'll receive a 500: Internal Server Error response when something goes wrong on our side.
{
  "type": "internal_server_error",
  "message": "An error has occurred, try your request again. If you still keep getting this error, please get in touch with Support."
}

Service Quota

Pagination

Last modified 1mo ago

Code	Description
`200`	Everything worked as expected.
`204`	The resource is deleted.
`400`	The request has missing arguments or is malformed. See examples of these types of errors.
`401`	The request is not authenticated.
`402`	The request is not available as payment is due. This is only returned for users on our credit-based plans.
`403`	The request is authenticated but does not have sufficient permissions.
`404`	The resource requested does not exist.
`413`	The request is too large.
`422`	A processing error has occurred.
`429`	The rate limit or service quota has been breached.
`500`	Something is wrong on our end. Subscribe to our status page to be notified of any incident.

Error	Description
`two_sides_expected`	Returned when only one side of a supported document type is provided before running a check. Applies to Document Check.
`unsupported_document_format`	Returned when an unsupported document attachment format is provided before running a check. Applies to Document Check.
`unsupported_document_type_country`	Returned when a check is run against an unsupported ID type and country combination. Applies to Document Check.
`document_requires_issuing_country`	Returned when a check is run against a document with a missing `issuingCountry` attribute. Applies to Document Check.
`document_type_undetected`	Returned when an unsupported document type is checked. It could also be returned when the image quality is inadequate to recognize the document. Applies to Document Check and eligible Document uploads.
`invalid_check_update`	Returned when an update request is made on an unmodifiable check type. Only Standard Screening Checks and Extensive Screening Checks can be updated.
`pending_check_unmodifiable`	Returned when an update request is made on a check with a status of 'pending'.
`image_unreadable`	Returned when ComplyCube is not able to read data from a document image. This may occur when the image is of low quality or is incorrectly oriented. Applies to Document Check and eligible Document uploads.
`under_exposure`	Returned when the uploaded document image is too dark. This may occur when the image is underexposed. Applies to eligible Document uploads.
`excessive_glare`	Returned when the uploaded document image has excessive glare. Applies to eligible Document uploads.
`document_liveness_failed`	Returned when a document photo is deemed likely as spoofed, i.e., not live. It could also be returned when the image quality is inadequate to establish the liveness. Applies to eligible Document uploads.
`document_photocopy_detected`	Returned when a document photo is deemed to be a photocopy. Applies to eligible Document uploads.
`invalid_image_format`	Returned when an invalid image format is provided. Applies to Live Photo, Identity Check, and Document Check.
`liveness_failed`	Returned when a live photo is deemed likely as spoofed, i.e., not live. It could also be returned when the image quality is inadequate to establish the liveness. Applies to Live Photo.
`multiple_faces_detected`	Returned when multiple faces are detected. The client must retake the live photo. Applies to Live Photo.
`no_face_detected`	Returned when no faces are detected. The client must retake the live photo. Applies to Live Photo.
`face_not_centred`	Returned when a face is not centered. The client must retake the live photo. Applies to Live Photo.
`facial_features_obstructed`	Returned when facial features are obstructed. The client must retake the live photo. Applies to Live Photo.
`face_too_small`	Returned when the face is too small. The client must come closer and retake the live photo. Applies to Live Photo.
`face_too_close`	Returned when the face is too close. The client must move away from the camera and retake the live photo. Applies to Live Photo.
`face_not_centered`	Returned when the face is too close to the edge of the photo. The client must center their face and retake the live photo. Applies to Live Photo.
`face_cropped`	Returned when the face has been cropped. The client must retake the photo with their entire face in the frame. Applies to Live Photo.
`unsupported_poa_document_type`	Returned when a check is run against an unsupported proof of address document. Applies to Proof of Address Check.
`unsupported_country`	Returned when a check is run against an unsupported country. Applies to Multi-Bureau Check.
`missing_address_attributes`	Returned when a check is run while lacking the minimum required address attributes. Applies to Multi-Bureau Check.
`missing_client_attributes`	Returned when a check is run while lacking the minimum required client attributes. Applies to Multi-Bureau Check.
`invalid_id_number_format`	Returned when a check is run with an incorrectly formatted ID Number for a given country (e.g., SSN, Social Insurance Number). Applies to Multi-Bureau Check.
`image_too_large`	Returned when the image provided is too large. Applies to Document, Live Photo, Identity Check, and Document Check.