Error Handling

The API uses standard HTTP status codes to indicate success or failure. Errors include a JSON body with additional information.

HTTP Status Codes

Code	Meaning
200 OK	Request succeeded
201 Created	Resource created successfully
400 Bad Request	Invalid request (e.g., wrong flow, canceled resource)
401 Unauthorized	Missing or invalid authentication
403 Forbidden	Authenticated but not authorized for this action
404 Not Found	Resource not found
422 Unprocessable Entity	Validation failed
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Server error

Error Response Structure

Validation Errors (422)

{
  "message": "The person.first_name field is required when person is present. (and 1 more errors)",
  "errors": {
    "person.first_name": [
      "The person.first_name field is required when person is present."
    ],
    "person.last_name": [
      "The person.last_name field must be a string."
    ]
  }
}

Field	Description
message	Human-readable summary of the error(s)
errors	Object where keys are field names and values are arrays of error messages

Business Rule Errors (400)

{
  "message": "The verification is canceled."
}

Field	Description
message	Description of why the request was rejected

Common business rule errors:

Error	Scenario
Invalid verification flow.	Verification does not belong to the specified flow
The verification is canceled.	Attempting to modify a canceled verification
The verification has already started.	Attempting to upload documents after submission
Document type not allowed.	Document type is not configured for this flow
The verification already has a Photo ID document.	Duplicate document type upload
The document is canceled.	Attempting to make a decision on a canceled document
The document could not be created by missing data, please check the info and try again.	Missing required data for document creation

Not Found Errors (404)

{
  "message": "Not found."
}

Authentication Errors (401)

{
  "message": "Unauthenticated."
}

Rate Limit Errors (429)

{
  "message": "Too Many Attempts."
}

Handling Errors

Retry Strategy

For transient errors (5xx, timeout):

• Use exponential backoff with jitter
• Start with 1 second, double each retry, max 30 seconds
• Maximum 3 retries

Example retry intervals: 1s → 2s → 4s → 8s → 16s → 30s (cap)

Idempotent Operations

The following operations are safe to retry:

• GET requests (always safe)
• PUT requests (submit, resubmit, cancel, approve, reject)
• DELETE requests

POST requests (create, upload) are generally not safe to retry as they may create duplicate resources.