Skip to main content
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.
AttributeTypeDescription
errorCodestringA unique code in the format PREFIX-NUMBER that identifies the error.
errorMsgstringA human-readable message summarizing the error.
detailsarrayAn array of issue objects providing specific context about what went wrong.
details.issuestringA detailed description of the specific issue.
details.issueLocationstringThe location in the request payload, path, or header where the issue occurred (e.g., body.individual.dateOfBirth).
requestIdstringThe unique ID for the API request, which should be logged and provided to support if you need assistance.

​
Example Error Object

Here is an example of an error returned when an invalid entity ID is provided in the request path. 
{
    "details": [
        {
            "issue": "entity with ID '019930f5-6d09-739e-82ca-e597bf0ed98c' does not exist"
        }
    ],
    "errorCode": "VAL-404",
    "errorMsg": "Not Found",
    "requestId": "01K4VRM3WDE0X6MMP83HCDEWHC"
}

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

PrefixDescription
APIErrors in your API message, such as an incorrectly constructed URL or method.
AUTHAuthorization or security-related errors, like a missing or invalid API key.
VALAPI data validation errors. The details array will specify which fields are invalid.
ENTErrors related directly to Entity functions (e.g., an entity not found).
DOCErrors related directly to Document functions.
CHECKErrors related to Check/Verify functions. Indicates a problem with performing a check, not the result of the check itself.
SYSSystem-level errors on the FrankieOne side. These may be temporary.
CODEUnexpected errors detected in the code. Please contact support if you see these.
ADMINAdmin API errors. Please contact developer support if you receive one.

​
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: 
{
    "details": [
        {
            "issue": "request body has an error: registrationDetails value must be an array",
            "issueLocation": "Request",
            "issueType": "Bad Request"
        }
    ],
    "errorCode": "VAL-400",
    "errorMsg": "Bad Request",
    "requestId": "01K4VSB88WT4QG03MYCZJ9AEC4"
}
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: 
{
  "errorCode": "API-1010",
  "errorMsg": "Requested resource is not found",
  "details": [
    {
      "issue": "The specified resource '01BFJA617JMJXEW6G7TDDXNSHX' of type 'entity' does not exist",
      "issueLocation": "path"
    }
  ],
  "requestId": "01BFJA617JMJXEW6G7TDDXNSHX"
}
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: 
{
  "errorCode": "SYS-0007",
  "errorMsg": "No service providers available/configured. Contact developer support",
  "httpStatusCode": 503,
  "details": [
    {
      "issue": "The service is temporarily unavailable",
      "issueLocation": "server"
    }
  ],
  "requestId": "01GVEDZ0C1Q9NWQ699DBBKPE4Y"
}
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.