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 type of errors.
401	The request is not authenticated.
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 not adequate for the document to be recognised. Applies to Document Check.
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.
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 not adequate for the liveness to be established. Applies to Live Photo.
invalid_image_format	Returned when an invalid image format is provided. Applies to Live Photo, Identity Check and Document Check.
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.
facial_features_obstructed	Returned when facial features are obstructed. The client must retake the live photo. Applies to Live Photo.
eyes_closed	Returned when eyes are closed. Applies to Live Photo.
face_not_straight	Returned when the face is not straight. Applies to Live Photo.
excessive_glare	Returned when excessive glare is detected. Applies to Live Photo.
under_exposure	Returned when the image is dark. Applies to Live Photo.
image_blurry	Returned when blur is detected. Applies to Live Photo.
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."
}