> ## 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.
# Error Handling
> The FrankieOne API uses a standardized error format to ensure that you can reliably handle issues that arise from bad requests, server problems, or invalid data. All non-2xx responses will return a consistent JSON error object.
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`.
| Attribute | Type | Description |
| :-------------------- | :------ | :------------------------------------------------------------------------------------------------------------------- |
| errorCode | string | A unique code in the format `PREFIX-NUMBER` that identifies the error. |
| errorMsg | string | A human-readable message summarizing the error. |
| httpStatusCode | integer | The standard HTTP status code for the response (e.g., 400, 404, 500). |
| details | array | An array of issue objects providing specific context about what went wrong. |
| details.issue | string | A detailed description of the specific issue. |
| details.issueLocation | string | The location in the request payload, path, or header where the issue occurred (e.g., `body.individual.dateOfBirth`). |
| requestId | string | The 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 due to an invalid date of birth format in the request body.
```json theme={null}
{
"errorCode": "VAL-1002",
"errorMsg": "Data supplied is incorrect/badly formatted",
"httpStatusCode": 400,
"details": [
{
"issue": "Invalid format. Must be YYYY-MM-DD",
"issueLocation": "dateOfBirth"
}
],
"requestId": "01HN9XHZN6MGXM9JXG50K59Q85"
}
```
***
## 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)
| Prefix | Description |
| :----- | :------------------------------------------------------------------------------------------------------------------------- |
| API | Errors in your API message, such as an incorrectly constructed URL or method. |
| AUTH | Authorization or security-related errors, like a missing or invalid API key. |
| VAL | API data validation errors. The details array will specify which fields are invalid. |
| ENT | Errors related directly to Entity functions (e.g., an entity not found). |
| DOC | Errors related directly to Document functions. |
| CHECK | Errors related to Check/Verify functions. Indicates a problem with performing a check, not the result of the check itself. |
| SYS | System-level errors on the FrankieOne side. These may be temporary. |
| CODE | Unexpected errors detected in the code. Please contact support if you see these. |
| ADMIN | Admin 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. 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:**
```json theme={null}
{
"errorCode": "VAL-1001",
"errorMsg": "Missing required field",
"httpStatusCode": 400,
"details": [
{
"issue": "The 'familyName' field is required but was not provided",
"issueLocation": "body.individual.name.familyName"
},
{
"issue": "The dateOfBirth is invalid, provide a valid date",
"issueLocation": "dateOfBirth"
}
],
"requestId": "01HMR2ERSKCYAVXKS1FKSRT2T4"
}
```
**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:**
```json theme={null}
{
"errorCode": "API-1010",
"errorMsg": "Requested resource is not found",
"httpStatusCode": 404,
"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.
#### Scenario: A service provider required for a check is temporarily unavailable.
**Example Response:**
```json theme={null}
{
"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.
***
## Full List of Error Codes
Returned by internal processes. Generally indicate a temporary issue, but please contact developer support if the issue persists.
| Error Number | HTTP Error Code | Description |
| :----------- | :-------------- | :------------------------------------------------------------------------------------------------------------------------ |
| 0000 | 500 | Unknown internal error. Contact developer support |
| 0001 | 500 | Internal error. Contact developer support. |
| 0002 | 401 | Not authorised to perform this function |
| 0003 | 500 | Internal error. Contact developer support. |
| 0004 | 500 | Internal error. Contact developer support. |
| 0005 | 500 | Internal error. Contact developer support. |
| 0006 | 500 | Internal error. Contact developer support. |
| 0007 | 503 | No service providers available/configured. Contact developer support |
| 0008 | 503 | No document scanning service available/configured. Contact developer support |
| 0009 | 503 | No document verification service available/configured. Contact developer support |
| 0010 | 503 | No comparison service available/configured. Contact developer support |
| 0011 | 503 | No industry service available/configured. Contact developer support |
| 0012 | 501 | Requested service (comparison) isn't supported for your current configuration. Contact developer support. |
| 0013 | 501 | Requested service (scan) isn't supported for your current configuration. Contact developer support. |
| 0014 | 501 | Requested service (document verify) isn't supported for your current configuration. Contact developer support. |
| 0015 | 501 | Requested service (industry function) isn't supported for your current configuration. Contact developer support. |
| 0016 | 501 | Requested service (entity verify) isn't supported for your current configuration. Contact developer support. |
| 0017 | 501 | Requested service (specific entity check type) isn't supported for your current configuration. Contact developer support. |
| 0018 | 503 | No entity verification service available/configured. Contact developer support |
| 0019 | 503 | Internal error. Contact developer support. |
| 0020 | 500 | Internal error. Contact developer support. |
| 0021 | 500 | Internal error. Contact developer support. |
| 0022 | 500 | Internal error. Contact developer support. |
| 0023 | 500 | Internal error. Contact developer support. |
| 0024 | 500 | Internal error. Contact developer support. |
| 0025 | 500 | Internal error. Contact developer support. |
| 0026 | 500 | Internal error. Contact developer support. |
| 0027 | 500 | Internal error. Contact developer support. |
| 0028 | 500 | Internal error. Contact developer support. |
| 0029 | 500 | Internal error. Contact developer support. |
| 0030 | 500 | Internal error. Contact developer support. |
| 0031 | 500 | Internal error. Contact developer support. |
| 0032 | 500 | Cache retrieve error. Contact developer support. |
| 0033 | 500 | Internal error. Contact developer support. |
| 0034 | 500 | Internal error. Contact developer support. |
| 0035 | 503 | Push to mobile service not available |
Returned when no distinct error code is available (usually internal framework generated).
| Error Number | HTTP Error Code | Description |
| :----------- | :-------------- | :------------------------------------------------ |
| 400 | 400 | Generic 400 Error - See error message for details |
| 401 | 401 | Generic 401 Error - See error message for details |
| 404 | 404 | Generic 404 Error - See error message for details |
| 405 | 405 | Generic 405 Error - See error message for details |
| 415 | 415 | Generic 415 Error - See error message for details |
| 422 | 422 | Generic 422 Error - See error message for details |
| 429 | 429 | Generic 429 Error - See error message for details |
| 500 | 500 | Generic 500 Error - See error message for details |
| 501 | 501 | Generic 501 Error - See error message for details |
| 503 | 503 | Generic 503 Error - See error message for details |
The API returns these errors when it receives unsupported or missing header data.
| Error Number | HTTP Error Code | Description |
| :----------- | :-------------- | :-------------------------- |
| 801 | 400 | Missing header: RequestID |
| 802 | 400 | Missing header: CheckID |
| 901 | 400 | Malformed header: RequestID |
| 902 | 400 | Malformed header: CheckID |
The API returns these errors when it encounters issues with specific requests.
| Error Number | HTTP Error Code | Description |
| :----------- | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
| 1001 | 400 | Blank value supplied when one needed |
| 1002 | 400 | Data supplied is incorrect/badly formatted. |
| 1003 | 405 | Can't merge different documents or entities |
| 1004 | 400 | Can't set document ID |
| 1005 | 400 | Data conversion issue |
| 1006 | 422 | Document supplied is unparsable |
| 1007 | 400 | Can't set entity ID |
| 1008 | 400 | Entity supplied is unparsable |
| 1009 | 404 | Requested document isn't found |
| 1010 | 404 | Requested entity isn't found |
| 1011 | 422 | Not enough data supplied to perform requested check |
| 1012 | 500 | Can't mark record as deleted |
| 1013 | 400 | Utility bill not supplied |
| 1014 | 400 | Document not a PDF when PDF expected |
| 1015 | 400 | Scan data not supplied when scan expected |
| 1016 | 501 | Error response returned from utility processor |
| 1017 | 202 | Verification results incomplete - expect a notification push |
| 1018 | 415 | Media type not supported |
| 1019 | 400 | End date before start date |
| 1020 | 400 | Bad page number |
| 1021 | 400 | Bad page count request |
| 1022 | 404 | Requested check ID not found |
| 1023 | 404 | Can't retrieve original document |
| 1024 | 404 | Cache returned a nil result |
| 1025 | 400 | Geocode empty |
| 1026 | 400 | Multiple geocode results or inexact address match |
| 1027 | 400 | Bad geocode result - Address not found |
| 1028 | 400 | Invalid country or country code |
| 1029 | 401 | Attempt to access unauthorised data |
| 1030 | 400 | Entity state precludes requested flag setting |
| 1041 | 400 | Identity document required |
| 1042 | 400 | Incorrect ID type |
| 1043 | 400 | Missing mobile number |
| 1044 | 400 | Missing name |
| 1045 | 400 | Empty name |
| 1046 | 400 | Entity ineligible for service or in unsupported jurisdiction |
| 1047 | 400 | Push to Mobile service returned PTM service offline |
| 1048 | 404 | PTM service couldn't find the token requested |
| 1049 | 404 | Internal error. Contact developer support. |
| 1050 | 503 | No business query service available at this time. |
| 1051 | 503 | Failed to schedule background job |
| 1052 | 500 | Business processor returned empty result set |
| 1053 | 400 | Supplied entity isn't of a suitable type |
| 1054 | 400 | The requested operation amounted to no work |
| 1055 | 400 | A required prior result has expired |
| 1056 | 500 | The background operation couldn't continue because required data was modified |
| 1057 | 500 | The background operation couldn't continue because required data was missing |
| 1058 | 500 | No result was obtained in a reasonable time |
| 1059 | 500 | Inconsistent result from business processor |
| 1060 | 400 | Mismatch between ownership request and ABR response |
| 1061 | 400 | Can't change status of check result |
| 1062 | 403 | Operation not permitted, entity is in inactive state |
| 1063 | 500 | Report service exists but failed to generate a report or we couldn't save the result |
| 1064 | 400 | Document not owned by entity requested in document/verify function |
| 1065 | 400 | Named entity profile not configured |
| 1066 | 400 | Entity doesn't have an assigned profile |
| 1067 | 400 | Entity profiles aren't enabled for customer |
| 1068 | 400 | Missing application id or referrer when requesting an IDV token |
| 1069 | 400 | Invalid request to token service for a token |
| 1070 | 422 | Invalid request (unprocessable) to token service for a token |
| 1072 | 400 | Refresh token with mismatch applicant id |
| 1073 | 500 | The expected or default policy isn't configured |
| 1074 | 500 | Attempt to toggle entity monitoring failed |
| 1075 | 422 | Importing past results failed |
| 1076 | 400 | Unknown business reportType |
| 1077 | 503 | No intl business service available |
| 1078 | 400 | No intl business search/profile criteria provided |
| 1079 | 400 | Intl business service rejected request |
| 1080 | 400 | No shared blocklist |
| 1081 | 400 | No shared blocklist reason |
| 1082 | 500 | Shared blocklist internal error |
| 1083 | 500 | Failed to get JWT signer or JWK key set |
| 1084 | 400 | Entity not in valid state for setting a manual state |
| 1085 | 404 | Requested entity isn't retrievable at this time. NOTE: This is USUALLY transient, so wait 5 seconds and then retry |
| 1086 | 404 | Requested association doesn't exist |
| 1087 | 400 | Requested association isn't allowed |
| 1088 | 400 | Object not found from non-primary key search |
| 1089 | 500 | Internal error. Contact developer support. |
| 1090 | 400 | Device data supplied is either missing or incorrectly formatted |
| 1091 | 500 | Internal service error - please contact technical support |
| 1092 | 404 | Organisation can't be found in the requested country's registry |
| 1093 | 400 | The request contains an invalid parameter or argument |
| 1094 | 400 | Search criteria too broad and returned too many results. Please retry with narrower search criteria |
| 1095 | 400 | Incorrectly formatted organisation number |
| 1096 | 400 | The requested country registry is incorrect. Please ensure you have the right country registry code |
| 1097 | 503 | Unknown response from the registry |
| 1098 | 400 | No company registry for the requested country is available to query. This is often due to local regulations not making this data available |
| 1099 | 400 | Search by organisation\_number not available for the jurisdiction |