Understanding Issues

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:

Example: 400 Bad Request Error Response

1
{
2
  "errorCode": "API-0400",
3
  "errorMsg": "Multiple Errors: See Issues list",
4
  "details": [
5
    {
6
      "issue": "entityId in path must be of type uuid: \"test\"",
7
      "issueLocation": "VALIDATE-entityId"
8
    }
9
  ],
10
  "requestId": "01HM5XJ7VASZ3EJMB1VQGTBFJ4"
11
}

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).

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.

Example: Workflow-Execution-Summary with an Issue

1
{
2
  "workflowName": "kyc_onboarding",
3
  "workflowExecutionId": "01HNE42K1T6JXV41S8W5W8W6X8",
4
  "status": "REVIEW",
5
  "issues": [
6
    {
7
      "issueId": "01HNE42K2G4S8Z6G8Y4Y7B3A2C",
8
      "category": "AML",
9
      "issue": "SANCTION",
10
      "severity": "CRITICAL",
11
      "isCleared": false,
12
      "createdAt": "2024-05-15T02:18:11.365Z"
13
    }
14
  ]
15
}

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