Error Handling - frankieone

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.

{
  "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:

{
  "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

System Errors (0000 - 0399)

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

Generic Errors (0400 - 0599)

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

Header Errors (0800 - 0999)

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

Application & Service Errors (1000 - )

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

​The Error Object

​Example Error Object

​Understanding Error Codes

​Issue Location Codes (Prefix)

​Frontend Orchestration & Handling Errors

​400 - Bad Request (VAL-xxxx)

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

​404 - Not Found (API-1010)

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

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

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

​Full List of Error Codes

The Error Object

Example Error Object

Understanding Error Codes

Issue Location Codes (Prefix)

Frontend Orchestration & Handling Errors

400 - Bad Request (VAL-xxxx)

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

404 - Not Found (API-1010)

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

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

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

Full List of Error Codes