Skip to main content

Error Response Format

{
  "error": {
    "code": "invalid_document",
    "message": "The document image could not be processed",
    "type": "validation_error",
    "param": "document_front",
    "request_id": "req_a1b2c3d4"
  }
}

HTTP Status Codes

StatusDescription
200Success
201Created
400Bad Request - Invalid parameters
401Unauthorized - Invalid API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
409Conflict - Resource already exists
429Too Many Requests - Rate limited
500Server Error - Something went wrong

Error Types

TypeDescription
validation_errorInvalid request parameters
authentication_errorAPI key issues
authorization_errorPermission issues
not_found_errorResource not found
rate_limit_errorRate limit exceeded
idempotency_errorIdempotency key conflict
api_errorInternal server error

Common Error Codes

Authentication Errors

CodeDescription
unauthorizedMissing or invalid API key
forbiddenAPI key lacks required permissions
key_revokedAPI key has been revoked
ip_not_allowedRequest from non-whitelisted IP

Validation Errors

CodeDescription
invalid_requestRequest body is malformed
missing_parameterRequired parameter is missing
invalid_parameterParameter value is invalid
invalid_documentDocument image cannot be processed
unsupported_countryCountry not supported
unsupported_documentDocument type not supported

Identity Errors

CodeDescription
document_expiredDocument has expired
document_unreadableCannot extract data from document
face_not_detectedNo face found in image
face_mismatchSelfie doesn’t match document
liveness_failedLiveness check failed
fraud_detectedDocument tampering detected

Transaction Errors

CodeDescription
transaction_declinedTransaction was declined
velocity_exceededRate limit exceeded
recipient_blockedRecipient is blocklisted
amount_exceededAmount exceeds limits

Rate Limit Errors

CodeDescription
rate_limit_exceededToo many requests
Response includes retry_after field:
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "retry_after": 30
  }
}

Handling Errors

try {
  const result = await txcloud.identity.verify({ ... });
} catch (error) {
  switch (error.code) {
    case 'invalid_document':
      // Ask user to retake photo
      break;
    case 'face_mismatch':
      // Ask user for new selfie
      break;
    case 'rate_limit_exceeded':
      // Wait and retry
      await sleep(error.retryAfter * 1000);
      break;
    default:
      // Log and show generic error
      console.error('API error:', error);
  }
}