Error Handling

This guide explains the structure of the error object, provides a full list of error codes, and offers practical advice on how to handle these errors in your frontend application.

The Error Object

All errors returned from the FrankieOne API are wrapped in a standard ErrorObject.

Example Error Object

Here is an example of an error returned when an invalid entity ID is provided in the request path.

1
{
2
    "details": [
3
        {
4
            "issue": "entity with ID '019930f5-6d09-739e-82ca-e597bf0ed98c' does not exist"
5
        }
6
    ],
7
    "errorCode": "VAL-404",
8
    "errorMsg": "Not Found",
9
    "requestId": "01K4VRM3WDE0X6MMP83HCDEWHC"
10
}

Understanding Error Codes

The errorCode is a combination of a prefix (the Issue Location) and a number. This structure helps you quickly identify the source of the problem.

Issue Location Codes (Prefix)

Frontend Orchestration & Handling Errors

A robust frontend application should interpret the HTTP status code and the errorCode to present the user with a clear and helpful message.

400 - Bad Request (VAL-xxxx)

This is the most common error category. It means the user has provided invalid or incomplete data. You should validate the request parameters and body and retry the API. Your frontend should parse the details array to provide specific feedback.

Example Response:

1
{
2
    "details": [
3
        {
4
            "issue": "request body has an error: registrationDetails value must be an array",
5
            "issueLocation": "Request",
6
            "issueType": "Bad Request"
7
        }
8
    ],
9
    "errorCode": "VAL-400",
10
    "errorMsg": "Bad Request",
11
    "requestId": "01K4VSB88WT4QG03MYCZJ9AEC4"
12
}

Frontend Action:

• Iterate through the details array.
• For each issue, use the issueLocation to find the corresponding input field in your form.
• Display the issue message directly below that field.

This provides targeted, inline validation feedback to the user so they can easily correct their mistakes.

404 - Not Found (API-1010)

This means the resource you requested (like an entityId or workflowExecutionId) does not exist. You should validate the request parameters and retry the API.

Scenario: Your application tries to fetch results for a workflow that has been deleted or whose ID is incorrect.

Example Response:

1
{
2
  "errorCode": "API-1010",
3
  "errorMsg": "Requested resource is not found",
4
  "details": [
5
    {
6
      "issue": "The specified resource '01BFJA617JMJXEW6G7TDDXNSHX' of type 'entity' does not exist",
7
      "issueLocation": "path"
8
    }
9
  ],
10
  "requestId": "01BFJA617JMJXEW6G7TDDXNSHX"
11
}

Frontend Action:

• Check for the 404 status code.
• Redirect the user to a “Not Found” page or display a clear message like “We could not find the record you were looking for. Please check the ID or start a new search.”
• Avoid showing a generic “An error occurred” message, as this is a specific and actionable state.

5xx - Server & System Errors (SYS-xxxx)

These errors indicate a problem on FrankieOne’s side. The issue may be temporary. You can retry the API after a short delay.

Scenario: A service provider required for a check is temporarily unavailable.

Example Response:

1
{
2
  "errorCode": "SYS-0007",
3
  "errorMsg": "No service providers available/configured. Contact developer support",
4
  "httpStatusCode": 503,
5
  "details": [
6
    {
7
      "issue": "The service is temporarily unavailable",
8
      "issueLocation": "server"
9
    }
10
  ],
11
  "requestId": "01GVEDZ0C1Q9NWQ699DBBKPE4Y"
12
}

Frontend Action:

• Check for any 5xx status code (500, 503, etc.).
• Display a generic, user-friendly message, such as: “We’re sorry, something went wrong on our end. Please try again in a few moments.”
• Do not display the technical errorMsg to the user.
• You may implement a retry mechanism with exponential backoff for 503 errors, as these are often transient.
• Log the full error response, including the requestId, so you can report it to support if the issue persists.