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 due to an invalid date of birth format in the request body.

1
{
2
  "errorCode": "VAL-1002",
3
  "errorMsg": "Data supplied is incorrect/badly formatted",
4
  "httpStatusCode": 400,
5
  "details": [
6
    {
7
      "issue": "Invalid format. Must be YYYY-MM-DD",
8
      "issueLocation": "dateOfBirth"
9
    }
10
  ],
11
  "requestId": "01HN9XHZN6MGXM9JXG50K59Q85"
12
}

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. Your frontend should parse the details array to provide specific feedback.

Scenario: A user submits a form with an invalid date of birth and a missing family name.

Example Response:

1
{
2
  "errorCode": "VAL-1001",
3
  "errorMsg": "Missing required field",
4
  "httpStatusCode": 400,
5
  "details": [
6
    {
7
      "issue": "The 'familyName' field is required but was not provided",
8
      "issueLocation": "body.individual.name.familyName"
9
    },
10
    {
11
      "issue": "The dateOfBirth is invalid, provide a valid date",
12
      "issueLocation": "dateOfBirth"
13
    }
14
  ],
15
  "requestId": "01HMR2ERSKCYAVXKS1FKSRT2T4"
16
}

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.

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
  "httpStatusCode": 404,
5
  "details": [
6
    {
7
      "issue": "The specified resource '01BFJA617JMJXEW6G7TDDXNSHX' of type 'entity' does not exist",
8
      "issueLocation": "path"
9
    }
10
  ],
11
  "requestId": "01BFJA617JMJXEW6G7TDDXNSHX"
12
}

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.

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.

Full List of Error Codes