> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
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**
```json theme={null}
{
"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
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
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**
```json theme={null}
{
"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
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
| 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. |
| 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. |
| 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. |
| Issue Type | Description |
| :--------- | :--------------------------------------------------- |
| DECEASED | The person whose data is being verified is deceased. |
| 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. |
| Issue Type | Description |
| :--------- | :------------------------------------------- |
| DUPLICATE | The entity is a duplicate of another entity. |
| 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. |
| 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. |
| Issue Type | Description |
| :------------- | :----------------------------------------------------------------------- |
| CREDIT\_HEADER | Credit header information was returned as part of a credit agency check. |
**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](https://docs.frankieone.com/docs/ekyc-rulesets) page.
| Issue Type | Description |
| :--------------- | :---------------------------------------------------------------------- |
| SERVICE\_TIMEOUT | All providers have timed out. |
| SERVICE\_ERROR | All providers have returned an error or an internal error has occurred. |
| Issue Type | Description |
| :----------- | :----------------------------------- |
| DENY\_LIST | The entity matched a visa deny list. |
| VISA\_FAILED | Visa check failed from the provider. |
| 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 the`issues` array** in workflow results to drive automated decisions or flag cases for manual review.
* **Map`issueLocation`** to specific fields in your UI for targeted feedback.
* **Use`severity`** to determine whether to block, warn, or allow user progression.
* **Log`issueId` and `requestId`** for troubleshooting and support.
> ***Tip:***\
> *By building logic around issues, you can streamline compliance, automate onboarding, and improve user experience.*
***