> ## 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. | | 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 when an invalid entity ID is provided in the request path. ```json theme={null} { "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) | 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. 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:** ```json theme={null} { "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:** ```json theme={null} { "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:** ```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.