Overview
The Journey Blocking Mechanism is a security feature designed to prevent identity theft and fraudulent verification attempts in the KYC system. When users fail verification multiple times within a calendar day, they are temporarily blocked from further attempts.
- Blocking occurs after 5 failures in a calendar day
- Only failures after face capture count toward the limit
- Block duration is 2 hours
- Failures aggregate across all document types
- Counter resets at midnight (GST timezone) or after blocking duration, whichever is first
- Blocking is per user, per client
Blocking Mechanism
Block Trigger
The system blocks users after 5 failed Journeys (User KYC session) for any Journey type within a single calendar day.
| Parameter | Value |
|---|
| Failure Threshold | 5 failures per calendar day |
| Block Duration | 2 hours from the time of the 5th failure |
| Unblock Timing | Automatic unblock after 2 hours OR at midnight (GST), whichever is first |
Purpose
The 2-hour block period allows the security team time to investigate suspicious patterns and take necessary actions. Investigation details remain confidential and are not shared with end users.
Failure Counting Rules
What Counts as a Failure ✓
A journey counts as a failure only when:
- User successfully completes the face capture step, AND
- Verification fails after face capture (due to face match, ICP verification, or liveness check)
Common Failures That DO Count:
| Error Code | Description |
|---|
UAEKYC-ERR-AI-009 | Face match failed |
UAEKYC-ERR-AI-007 | Liveness failed (after face capture completed) |
UAEKYC-ERR-ICP-002 | ICP face match failed |
UAEKYC-ERR-JOURNEY-010 | No image for face match (after face capture) |
What Does NOT Count as a Failure ✗
The following scenarios DO NOT count toward the 5-failure blocking threshold:
Journey Abandonment
- Any scenario where face capture step is not completed
- User exits journey before reaching face capture
| Error Code | Description |
|---|
UAEKYC-ERR-JOURNEY-006 | Document extraction attempts exceeded |
UAEKYC-ERR-JOURNEY-008 | Document not allowed |
UAEKYC-ERR-AI-001 | Document extraction failed |
Technical/System Errors
| Error Code | Description |
|---|
UAEKYC-ERR-GLOBAL-002 | Internal server error |
UAEKYC-ERR-INT-* | Any internal system errors |
| Network timeout | Connection failures |
Other Exclusions
| Error Code | Description |
|---|
UAEKYC-ERR-GLOBAL-001 | Insufficient credits |
UAEKYC-ERR-GLOBAL-003 | Organisation not found |
UAEKYC-ERR-GLOBAL-004 | Rate limit exceeded |
UAEKYC-ERR-ICP-001 | Person not found (after face capture) |
Successful verifications DO NOT reset the failure counter. Once a failure is counted, it remains in the count until the counter resets at midnight.
Failure Counting Example
Day 1:- Journey 1: Fail → Count: 1- Journey 2: Fail → Count: 2- Journey 3: Success → Count: 2 (not reset)- Journey 4: Fail → Count: 3- Journey 5: Fail → Count: 4- Journey 6: Fail → Count: 5 → USER BLOCKED
Counter Reset
The failure counter resets at midnight (GST timezone) each day.
Document Type Handling
Cross-Document Aggregation
Failures are counted cumulatively across all document types. Users cannot bypass blocking by switching document types.
Example:
- 3 failures with Emirates ID | Journey Type = Onboarding- 1 failure with Passport | Journey Type = ReKYC- 1 failure with GCC ID | Journey Type = Onboarding= 5 total failures → User blocked
Journey Type Coverage
Blocking applies to all journey types:
- Onboarding - New customer verification
- ReKYC - Re-verification of existing customers
- Authorise - Authentication during transactions/logins
Blocked User Behavior
Journey Creation with User Identifier
When a blocked user provides their UAEKYC ID or Emirates ID number at journey initiation:
- Journey creation is prevented immediately
- API returns the blocked error message
- User cannot proceed with the journey
Journey Creation without User Identifier
When a blocked user does not provide identifier upfront:
- User can capture document
- System performs OCR to extract identifier
- Journey is blocked after OCR, before face capture
- User receives blocked error message
Notifications and Error Codes
Warning on 4th Failure
After the 4th failure, the API returns the following warning:
{ "code": "UAEKYC-WARN-JOURNEY-001", "type": "JOURNEY", "message": "Next failed attempt for the user will result in blockage."}
Block Error on 5th Failure
After the 5th failure, the user is blocked and the following error is returned:
{ "code": "UAEKYC-ERR-JOURNEY-015", "type": "JOURNEY", "message": "User has been blocked due to multiple failed attempts."}
Notification Channels
Clients are notified through multiple channels:
| Channel | Description |
|---|
| Journey API Response | Error code and message in response |
| Journey Status | New BLOCKED status |
| SDK Error Display | Error message shown in SDK interface |
Journey States
A new journey state BLOCKED has been introduced to handle blocked users attempting new journeys.
Complete Status List
The journey can have the following statuses:
NOT_STARTEDIN_PROGRESSCOMPLETEDREJECTEDABANDONEDADJUDICATEDEXPIREDBLOCKED ← New status
SDK Compatibility
All SDK Versions
Blocking functionality is supported across all SDK versions.
Legacy SDK Behavior
For older SDK versions:
- Journey fails with standard error response
- Clients can handle error code in their integration
Enhanced SDK (Version x.0.0 and Above)”)
For newer SDK versions:
- Custom blocked error page displayed
- Countdown timer showing remaining block duration
- Improved user experience
Dashboard Features
The UAE KYC Dashboard has been updated to support the blocking mechanism:
Journey Table Page
- New
BLOCKED filter added
- Filter journeys by blocked status
Journey Details Page
- Display new
BLOCKED status
- Show block-related information
Blocking Scope
Client-Level Blocking
Blocking applies at the individual client level. Users blocked by one client are not affected when attempting journeys with other clients.
User-Level Blocking
Blocking is tied to UAEKYC ID. Different users are not affected by each other’s failed attempts.
Global Configuration
The same blocking rules apply to all clients:
| Parameter | Value |
|---|
| Failure Threshold | 5 failures (standard) |
| Block Duration | 2 hours (standard) |
API Integration
Journey Creation API
When a blocked user attempts to create a journey, the API returns:
{ "status": "BLOCKED", "error": { "code": "UAEKYC-ERR-JOURNEY-015", "type": "JOURNEY", "message": "User has been blocked due to multiple failed attempts.", "timeRemaining": 7200 }}
timeRemaining is in seconds.
Journey Status API
The Journey Details API now returns the new status value:
BLOCKED - Added to existing statuses (NOT_STARTED, IN_PROGRESS, COMPLETED, REJECTED, ABANDONED, ADJUDICATED, EXPIRED)
Client Integration
Error Code Handling
Clients should handle the new error codes in their integration:
Warning Code (4th Failure)::“)
if (response.warning?.code === 'UAEKYC-WARN-JOURNEY-001') { // Display warning to user displayWarning('Next failed attempt will result in temporary blocking.');}
Block Error Code (5th Failure)::“)
if (response.error?.code === 'UAEKYC-ERR-JOURNEY-015') { // Display block message displayBlockMessage(response.error.message); // Calculate remaining time const remainingMinutes = Math.ceil(response.error.timeRemaining / 60); displayCountdown(remainingMinutes); // Prevent further journey attempts disableJourneyInitiation();}
Error Code Reference
Summary Table
| Code | Type | Message | Trigger |
|---|
UAEKYC-WARN-JOURNEY-001 | JOURNEY | Next failed attempt for the user will result in blockage. | 4th failure in calendar day |
UAEKYC-ERR-JOURNEY-015 | JOURNEY | User has been blocked due to multiple failed attempts. | 5th failure or blocked user attempts journey |
Best Practices
For Integrators
- Implement Warning Handling: Display the 4th failure warning prominently to users
- Show Remaining Time: When blocked, display countdown timer for better UX
- Graceful Degradation: Ensure older SDK versions handle blocking gracefully
- Error Logging: Log all blocking events for monitoring and analysis
For End Users
- Ensure Good Lighting: Take photos in well-lit environments
- Follow Instructions: Carefully follow on-screen instructions for document capture
- Stable Connection: Ensure stable internet connection during verification
- Contact Support: If repeatedly blocked, contact customer support
