Understanding Issues

A guide to the types of issues that can arise during KYC workflows and how to handle them.

Note:
In the FrankieOne v2.0.0 API, an “issue” is a fundamental concept used to communicate problems, errors, or specific outcomes that require attention. Issues can arise from simple input validation errors to complex workflow results that require manual review.

The Structure of an Issue

Core Issue Object

An issue is typically represented as an Issue object, which contains details about what went wrong and where. While the exact structure can vary slightly depending on the context (e.g., a synchronous API error vs. a workflow result), it generally contains the following key fields:

Field	Type	Description
issue	string	Human-readable description of the problem
issueLocation	string	Context/location where the issue was identified (e.g., `VALIDATE-entityId`)
issueType	string	(Optional) Category for the issue

Example: 400 Bad Request Error Response

{
  "errorCode": "API-0400",
  "errorMsg": "Multiple Errors: See Issues list",
  "details": [
    {
      "issue": "entityId in path must be of type uuid: \"test\"",
      "issueLocation": "VALIDATE-entityId"
    }
  ],
  "requestId": "01HM5XJ7VASZ3EJMB1VQGTBFJ4"
}

How Issues are Created

Direct API Error Responses

Synchronous errors occur when an API request cannot be fulfilled due to issues like invalid authentication, malformed requests, or server-side problems. The API returns a standard Error object with a relevant HTTP status code (e.g., 400, 401, 500).

Field	Description
errorCode	Unique FrankieOne code for the error (e.g., AUTH-0002)
errorMsg	Summary of the error (e.g., Unauthorized)
details	Array of Issue objects detailing each problem

Common Error Scenarios:

400 Bad Request: Validation errors (e.g., malformed entityId)
401 Unauthorized: Missing or invalid api_key
404 Not Found: Resource does not exist
5xx Server Error: Internal platform issues

Workflow Execution Results

When a workflow runs, the platform performs a series of checks. If any check produces a result that requires attention, a Workflow-Issue object is generated and included in the workflow execution summary.

Field	Type	Description
issueId	string	Unique identifier for the issue
category	string	Broad classification (e.g., AML, KYC, FRAUD, DOCUMENT)
issue	string	Specific issue type (e.g., SANCTION, NOT_FOUND)
severity	string	Severity level (INFO, REVIEW, BLOCK, WARNING, CRITICAL, ERROR)
isCleared	boolean	Indicates if the issue has been manually addressed/resolved
createdAt	string	Timestamp when the issue was created

Example: Workflow-Execution-Summary with an Issue

{
  "workflowName": "kyc_onboarding",
  "workflowExecutionId": "01HNE42K1T6JXV41S8W5W8W6X8",
  "status": "REVIEW",
  "issues": [
    {
      "issueId": "01HNE42K2G4S8Z6G8Y4Y7B3A2C",
      "category": "AML",
      "issue": "SANCTION",
      "severity": "CRITICAL",
      "isCleared": false,
      "createdAt": "2024-05-15T02:18:11.365Z"
    }
  ]
}

Issue Severity Levels

Severity	Description
INFO	Informational only, no action required
REVIEW	Requires manual review before proceeding
BLOCK	Blocks workflow completion until resolved
WARNING	Indicates a potential problem, but not blocking
CRITICAL	Serious issue, typically blocks onboarding
ERROR	Error state, usually requires technical intervention

Workflow Issue Categories

Issue Categories

This table lists the general categories that an issue can fall under.

Category	Description
AML	Anti-Money Laundering issues.
BAD_DATA	Indicates that the data provided is invalid or incorrect.
BIOMETRICS	Issues found during a biometrics check.
BLOCKLISTED	The entity has a hit on a blocklist.
DECEASED	Indicates that the entity is deceased.
DEVICE	Issues found during device checks.
DOCUMENT	Issues found during a document check.
DUPLICATE	Indicates that the entity has duplicates.
EXPIRY	Indicates that a process or document for the entity has expired.
FRAUD	Possible fraud detected.
IDV	Issues found during an Identity Verification (IDV) process.
INFORMATIONAL	Informational messages that are not issues but are required to be returned.
KYC	Issues found during a Know Your Customer (KYC) process.
SYSTEM	System-level issues.
VERIFY	Issues found during a verification process.
VISA	Issues found during a visa check.
WATCHLIST	Issues found during a watchlist check.
ACTIVITY	Issues found during an activity process.

Workflow Issue Types & Descriptions

AML & Watchlist

Issue Type	Description
PEP	The entity has Politically Exposed Person (PEP) hits.
SANCTION	The entity has sanction hits.
MEDIA	The entity has adverse media hits.
WATCHLIST	The entity has watchlist hits.
INTERNAL_MATCH	The entity matched an internal watchlist.
AML_ISSUE	General AML issue.

Bad Data

Issue Type	Description
BAD_DATA_NAME	Name is required but missing or unusable.
BAD_DATA_DOB	Date of Birth is required but missing or unusable.
BAD_DATA_ADDRESS	Address is required but missing or unusable.
BAD_DATA_ID	ID is required but missing or unusable.
BAD_DATA_EMAIL	Email is required but missing or unusable.
BAD_DATA_MOBILE	Mobile is required but missing or unusable.
BAD_DATA_DEVICE	Device is required but missing or unusable.
BAD_DATA_IP_ADDRESS	IP Address is required but missing or unusable.
BAD_DATA_EMAIL_ADDRESS	Email Address is required but missing or unusable.

Blocklist

Issue Type	Description
MATCHED_INTERNAL	The entity matched an internal blocklist.
MATCHED_SHARED	The entity matched a shared blocklist.
MATCHED_EXTERNAL	The entity matched an external blocklist.
BLOCKED	General blocklist issue.

Deceased

Issue Type	Description
DECEASED	The person whose data is being verified is deceased.

Device & Fraud

Issue Type	Description
DEVICE_FRAUD_MATCH	Fraud detected on the device.
DEVICE_INVALID	The device is invalid.
FRAUD_LIST	The entity is on a fraud list.
FRAUD_CHECK	Fraud detected during checks.
FRAUD_DEVICE	Device fraud detected.
FRAUD_IP_ADDRESS	IP address fraud detected.
FRAUD_EMAIL_ADDRESS	Email address fraud detected.
FRAUD_PHONE_NUMBER	Phone number fraud detected.
FRAUD_INCOMPLETE	The fraud check was incomplete.
FRAUD_ISSUE	General fraud issue.

Duplicate

Issue Type	Description
DUPLICATE	The entity is a duplicate of another entity.

Expiry

Issue Type	Description
REQUIRES_KYC	KYC process needs to be re-initiated.
REQUIRES_IDV	IDV process needs to be re-initiated.
REQUIRES_AML	AML process needs to be re-initiated.
REQUIRES_VISA	Visa process needs to be re-initiated.

Identity & Document Verification (IDV)

Issue Type	Description
DATA_COMPARISON	Data comparison issue.
DATA_VALIDATION	Data validation issue.
DATA_CONSISTENCY	Data consistency issue.
VISUAL_AUTHENTICITY	Visual authenticity issue.
IMAGE_INTEGRITY	Image integrity issue.
COMPROMISED_DOCUMENT	Document is compromised.
LIVENESS_DETECTION	Liveness detection failed.
DOCUMENT_COMPARISON	Document comparison issue.
OCR	The OCR data does not match what was entered by the user.

Informational

Issue Type	Description
CREDIT_HEADER	Credit header information was returned as part of a credit agency check.

KYC

KYC Summary Issue Codes

Issue Type	Description	Condition
PARTIAL	The KYC check was only partially successful.	Some data matched, but the total results were insufficient to pass the ruleset.
NOT_FOUND	No match was found for the given data.	The overall KYC ruleset requirements were not satisfied.

KYC Detailed Issue Codes

Issue Type	Description	Condition
NO_GOVID_MATCH	GovID required but no GovID match.	A Government ID was required, but no match was found in the system.
INSUFFICIENT_GOVID_MATCH	GovID required but insufficient matches.	Government ID matches were found, but they did not meet the required count.
NO_DOB_MATCH	DOB required but no DOB match.	A Date of Birth check was required, but no match was found.
INSUFFICIENT_DOB_MATCH	DOB required but insufficient matches.	Date of Birth matches were found, but they are below the required threshold.
NO_ADDRESS_MATCH	Address required but no address match.	An Address check was required, but no match was found.
INSUFFICIENT_ADDRESS_MATCH	Address required but insufficient matches.	Address matches were found, but they did not meet the full verification requirements.
NO_NAME_MATCH	Name required but no name match.	A Name check was required, but no match was found.
INSUFFICIENT_NAME_MATCH	Name required but insufficient matches.	Name matches were found, but they were fewer than the ruleset requires.
PARTIAL_MATCH	General partial match.	Multiple fields were verified successfully, but the overall verification resulted in a failure.

For more information on how these conditions are evaluated and configured, please refer to the KYC Ruleset page.

System

Issue Type	Description
SERVICE_TIMEOUT	All providers have timed out.
SERVICE_ERROR	All providers have returned an error or an internal error has occurred.

Visa

Issue Type	Description
DENY_LIST	The entity matched a visa deny list.
VISA_FAILED	Visa check failed from the provider.

Activity

Issue Type	Description
ACTIVITY_AML	AML-related activity issue.
ACTIVITY_FRAUD	Fraud-related activity issue.
ACTIVITY_DEVICE	Device-related activity issue.

Workflow Issue Severity Levels

Severity levels help determine the urgency and impact of an issue. Use them to drive workflow logic and user experience.

Severity	Description
INFO	Informational only.
REVIEW	Requires review.
BLOCK	Blocks further processing.
WARNING	Warning, but not blocking.
CRITICAL	Critical issue.
ERROR	Error encountered.

Best Practices for Handling Issues

Monitor theissues array in workflow results to drive automated decisions or flag cases for manual review.
MapissueLocation to specific fields in your UI for targeted feedback.
Useseverity to determine whether to block, warn, or allow user progression.
LogissueId and requestId for troubleshooting and support.

Tip:
By building logic around issues, you can streamline compliance, automate onboarding, and improve user experience.

​The Structure of an Issue

​How Issues are Created

​Issue Severity Levels

​Workflow Issue Categories

​Workflow Issue Types & Descriptions

​Workflow Issue Severity Levels

​Best Practices for Handling Issues

The Structure of an Issue

How Issues are Created

Issue Severity Levels

Workflow Issue Categories

Workflow Issue Types & Descriptions

Workflow Issue Severity Levels

Best Practices for Handling Issues