Sumsub Know Your Customer (KYC) Integration Guide

8. Error Handling and Retry Logic

Client systems should handle API errors, document upload issues, and retry outcomes consistently so incomplete KYC submissions can be corrected, resubmitted, and tracked through the review flow.

Updated 15 minutes ago

On this page

HTTP errors Document upload errors Retry flow for RETRY rejections Retry tracking Next steps

HTTP Errors

Code	Client Action
`200 / 201`	Success. Continue the flow.
`400`	Fix request payload. Check required fields, questionnaire values, and document metadata.
`401 / 403`	Check credentials, timestamp, signature, and exact signed body bytes.
`404`	Confirm `applicantId`, endpoint, and resource path.
`409`	Conflict. Applicant may already be pending or completed.

Common Document Upload Errors

Error	Meaning
`dataNotReadable`	Image unreadable. Retake photo.
`shouldBeDoubleSided`	Missing front or back side.
`sameSides`	Front and back images appear identical.
`forbiddenDocument`	Document type or country is not accepted on this level.
`selfieFaceBadQuality`	Face is not visible or image quality is too low.

Retry Flow for RETRY Rejections

When reviewRejectType = RETRY, use the same applicant record and collect only the corrected information needed to continue review.

1
Show the user a clear correction or resubmission message based on available rejection labels and applicant-facing comments.
2
Collect corrected documents or data.
3
Use the same applicantId.
4
Patch fixedInfo only if non-document fields changed.
5
Re-upload corrected documents.
6
Request review again with status/pending.

Retry Tracking

Keep retry attempts traceable by logging the original rejection labels, the correction requested, the updated document or data submitted, and the timestamp when the applicant was moved back to pending.

Next steps

Continue to Security Requirements for credential handling, request signing, and data protection expectations for the Sumsub KYC integration.