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.
httpStatusCodeintegerThe standard HTTP status code for the response (e.g., 400, 404, 500).
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 due to an invalid date of birth format in the request body. 
{
  "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)

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. 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: 
{
  "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: 
{
  "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: 
{
  "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 NumberHTTP Error CodeDescription
0000500Unknown internal error. Contact developer support
0001500Internal error. Contact developer support.
0002401Not authorised to perform this function
0003500Internal error. Contact developer support.
0004500Internal error. Contact developer support.
0005500Internal error. Contact developer support.
0006500Internal error. Contact developer support.
0007503No service providers available/configured. Contact developer support
0008503No document scanning service available/configured. Contact developer support
0009503No document verification service available/configured. Contact developer support
0010503No comparison service available/configured. Contact developer support
0011503No industry service available/configured. Contact developer support
0012501Requested service (comparison) isn’t supported for your current configuration. Contact developer support.
0013501Requested service (scan) isn’t supported for your current configuration. Contact developer support.
0014501Requested service (document verify) isn’t supported for your current configuration. Contact developer support.
0015501Requested service (industry function) isn’t supported for your current configuration. Contact developer support.
0016501Requested service (entity verify) isn’t supported for your current configuration. Contact developer support.
0017501Requested service (specific entity check type) isn’t supported for your current configuration. Contact developer support.
0018503No entity verification service available/configured. Contact developer support
0019503Internal error. Contact developer support.
0020500Internal error. Contact developer support.
0021500Internal error. Contact developer support.
0022500Internal error. Contact developer support.
0023500Internal error. Contact developer support.
0024500Internal error. Contact developer support.
0025500Internal error. Contact developer support.
0026500Internal error. Contact developer support.
0027500Internal error. Contact developer support.
0028500Internal error. Contact developer support.
0029500Internal error. Contact developer support.
0030500Internal error. Contact developer support.
0031500Internal error. Contact developer support.
0032500Cache retrieve error. Contact developer support.
0033500Internal error. Contact developer support.
0034500Internal error. Contact developer support.
0035503Push to mobile service not available
Returned when no distinct error code is available (usually internal framework generated).
Error NumberHTTP Error CodeDescription
400400Generic 400 Error - See error message for details
401401Generic 401 Error - See error message for details
404404Generic 404 Error - See error message for details
405405Generic 405 Error - See error message for details
415415Generic 415 Error - See error message for details
422422Generic 422 Error - See error message for details
429429Generic 429 Error - See error message for details
500500Generic 500 Error - See error message for details
501501Generic 501 Error - See error message for details
503503Generic 503 Error - See error message for details
The API returns these errors when it receives unsupported or missing header data.
Error NumberHTTP Error CodeDescription
801400Missing header: RequestID
802400Missing header: CheckID
901400Malformed header: RequestID
902400Malformed header: CheckID
The API returns these errors when it encounters issues with specific requests.
Error NumberHTTP Error CodeDescription
1001400Blank value supplied when one needed
1002400Data supplied is incorrect/badly formatted.
1003405Can’t merge different documents or entities
1004400Can’t set document ID
1005400Data conversion issue
1006422Document supplied is unparsable
1007400Can’t set entity ID
1008400Entity supplied is unparsable
1009404Requested document isn’t found
1010404Requested entity isn’t found
1011422Not enough data supplied to perform requested check
1012500Can’t mark record as deleted
1013400Utility bill not supplied
1014400Document not a PDF when PDF expected
1015400Scan data not supplied when scan expected
1016501Error response returned from utility processor
1017202Verification results incomplete - expect a notification push
1018415Media type not supported
1019400End date before start date
1020400Bad page number
1021400Bad page count request
1022404Requested check ID not found
1023404Can’t retrieve original document
1024404Cache returned a nil result
1025400Geocode empty
1026400Multiple geocode results or inexact address match
1027400Bad geocode result - Address not found
1028400Invalid country or country code
1029401Attempt to access unauthorised data
1030400Entity state precludes requested flag setting
1041400Identity document required
1042400Incorrect ID type
1043400Missing mobile number
1044400Missing name
1045400Empty name
1046400Entity ineligible for service or in unsupported jurisdiction
1047400Push to Mobile service returned PTM service offline
1048404PTM service couldn’t find the token requested
1049404Internal error. Contact developer support.
1050503No business query service available at this time.
1051503Failed to schedule background job
1052500Business processor returned empty result set
1053400Supplied entity isn’t of a suitable type
1054400The requested operation amounted to no work
1055400A required prior result has expired
1056500The background operation couldn’t continue because required data was modified
1057500The background operation couldn’t continue because required data was missing
1058500No result was obtained in a reasonable time
1059500Inconsistent result from business processor
1060400Mismatch between ownership request and ABR response
1061400Can’t change status of check result
1062403Operation not permitted, entity is in inactive state
1063500Report service exists but failed to generate a report or we couldn’t save the result
1064400Document not owned by entity requested in document/verify function
1065400Named entity profile not configured
1066400Entity doesn’t have an assigned profile
1067400Entity profiles aren’t enabled for customer
1068400Missing application id or referrer when requesting an IDV token
1069400Invalid request to token service for a token
1070422Invalid request (unprocessable) to token service for a token
1072400Refresh token with mismatch applicant id
1073500The expected or default policy isn’t configured
1074500Attempt to toggle entity monitoring failed
1075422Importing past results failed
1076400Unknown business reportType
1077503No intl business service available
1078400No intl business search/profile criteria provided
1079400Intl business service rejected request
1080400No shared blocklist
1081400No shared blocklist reason
1082500Shared blocklist internal error
1083500Failed to get JWT signer or JWK key set
1084400Entity not in valid state for setting a manual state
1085404Requested entity isn’t retrievable at this time. NOTE: This is USUALLY transient, so wait 5 seconds and then retry
1086404Requested association doesn’t exist
1087400Requested association isn’t allowed
1088400Object not found from non-primary key search
1089500Internal error. Contact developer support.
1090400Device data supplied is either missing or incorrectly formatted
1091500Internal service error - please contact technical support
1092404Organisation can’t be found in the requested country’s registry
1093400The request contains an invalid parameter or argument
1094400Search criteria too broad and returned too many results. Please retry with narrower search criteria
1095400Incorrectly formatted organisation number
1096400The requested country registry is incorrect. Please ensure you have the right country registry code
1097503Unknown response from the registry
1098400No company registry for the requested country is available to query. This is often due to local regulations not making this data available
1099400Search by organisation_number not available for the jurisdiction