Errors

While Trulioo aims to prevent errors during the API integration process, some basic errors may still occur. This page is designed to help you understand and resolve errors that may occur when using our API. Whether you're facing validation issues, authentication problems, or data errors, this page provides clear guidance to help you resolve any issues with our API.

If you encounter an error not listed here or need further assistance, please contact our support team for help.

Platform Errors

Below is a list of common errors you might encounter while using the Trulioo Platform API.

Code	Message	Additional Information
4000	Flow not found	Not applicable in production. Only happens with test URL.
4001	Flow theme not found	The theme you’ve set for your hosted workflow doesn’t exist.
4002	Node not found	A node has been removed and the workflow republished while an end user is currently on that node.
4003	Flow is empty	This only occurs while testing before any element has been added to the flow.
4006	Missing data for required element	The required fields have not been included in the Workflow payload.
4007	Submitted data is malformed	The field input doesn’t match the field type. For example, a string has been submitted for a "number only" field.
4008	Failed validation for submitted data	This can occur with string, number and date fields when Min and Max are defined.
4009	Service execution failed	The Trulioo service you’ve called in the workflow has returned an error.
4013	Flow already finished	The form your are submitting has already been submitted.
4014	Invalid submit data	This occurs for a specific service like eID.
4050	Invalid credentials	This occurs when there is an internal error for a specific service. Reach out to [email protected] and include the EndClient_ID
4100	Client not found	The Session ID is invalid.
4101	Client has no flow with given ID	The Session ID is invalid because workflow you are trying to access has been deleted.
4103	Illegal back action	This error only occurs if you use the back button to return to the Document Verification Service after submitting the document. You can also encounter this error via API if you trigger /back/{{flowID}} either at the start of the workflow or after completing the workflow.
4109	EndClient marked as abandoned	The form submission has occurred for an abandoned session ID
4110	Could not retrieve full end client data	Occurs when WFS cannot retrieve data from services and only happens for authenticated workflows if "End Lead Service Data" is enabled.
4200	Service not configured	Trulioo service has not been activated. Check all the services and republish.
4201	Service not configured for country	The country data being submitted is not defined at the service level.
5300	Invalid Twilio code	Integration with Twilio is required
5301	Failed to send SMS to phone number	KYB workflow connector with SMS has been chosen as communication type
5302	Twilio internal error	Integration with Twilio is required
6504	Service has timed out	The service hasn't responded within the expected timeframe. This error can occur when submitting the flow if the service is not responsive.

Http Errors

The API uses HTTP response codes to show the status of a request. Generally, 2xx codes mean success, 4xx codes mean there was an issue with the request (like a missing parameter or authentication header), and 5xx codes mean a server error. 5xx errors are rare and should be reported to Trulioo support.

Code	Message	Troubleshooting
400	BadRequest -Account not configured for this product	Ensure you are configured properly with the Get Country Codes request to see the countries you are configured for.
400	BadRequest -Configuration name not valid	For now, you should always send "Identity Verification" for the configuration name parameter.
400	BadRequest -Unable to find account	Email Trulioo support to ensure there are no issues with your account.
400	BadRequest -Transaction not available	Make sure that you are sending the correct TransactionRecordID and that the verify was sent from this same request.
400	BadRequest -Account not configured for this country.	Try the Get Country Codes request to see the countries you are configured for.
401	Unauthorized	The token you provided is not valid or you are using an account that is not enabled. Make a call to Test Authentication with your token. If you do not see your token echoed back at you, you are using an invalid token. Missing authorization header
413	Request Entity Too Large	If the request you sent is over the current limit.
415	UnsupportedMediaType	You asked for a media type that we do not support. Make sure your request includes a Content-Type: application/json header.
500	Error	An error happened on the server without a specific message. These are very rare, and should be handled by emailing Trulioo support.
500	Configuration name not valid	For now, you should always send "Identity Verification" for the configuration name parameter.
409	Error	The API requests have gone over the limit set for your account (not applicable for Enterprise users).
403	Error	The API key provided is invalid or expired.
404	Error	Cannot find the experience transaction for a given experience ID. Either the transaction ID does not exist or the entered one is incorrect.

Service Errors

Service errors are caused by invalid customer data, datasource errors, and address correction/address validation issues. Each error includes a code, indicating the category of service error, and a detailed error message.

Code	Message	Additional Information
1000	Provider Error - There was an error connecting to the source	One of the datasources your account is configured for may be experiencing an outage and was unreachable. The support team of Trulioo constantly monitors the datasources for such issues. This error only means that a single datasource could not be reached, so the requests to the other sources on your account should go through as normal.
1001	Missing Required Field	By running Get Fields you can see which fields are required for a specific country. This list of required fields is made up of a combination of mandatory fields across multiple datasources.
1002	Datasource Unavailable - the source did not respond	This error only means that a single datasource has failed to respond, so the requests to the other sources on your account should go through as normal. One of the datasources your account is configured for may have had an error and hasn't responded to Trulioo's request. Trulioo's support team is constantly monitoring datasources for such outages.
1003	Datasource Error - The source returned an error	This error only means that a single datasource could not be reached, so the requests to the other sources on your account should go through as normal. One of the datasources your account is configured for has returned an error in response to Trulioo's request. This happens on occasion and the support team of Trulioo constantly monitors the datasources for such errors. The vendor of that particular datasource will be contacted to understand and fix the issue.
1004	State not supported (AU Driver license)	Relevant to datasource AU (Australian) Driver license only. The state provided in the request is not supported by the datasource. Use the Get Country Subdivisions call to get a list of valid states/provinces/regions of a specific country.
1005	Missing consent - consent not sent for the source	Due to the nature of some of our datasources, you may need to acquire the consent from your customer for their data to be sent to this particular source. Use Get Consents to see which datasources require consent for a specific country. This will give you a list of datasource names that need consent in that country. If applicable, you will need to obtain these consents from your customer and provide them in the "ConsentForDataSources'' field of the Verify request.
1006	Unrecognized Field Name
1008	Invalid Field Format	The fields in a Verify request need to be of a specific data type. For example, FirstGivenName must be a UTF-8 string and DayOfBirth must be an Integer.
1009	Unrecognized Field group
1010	Request Timed Out	This error occurs when the transaction times out or the connection drops before completion. If you disconnect before the default 120-second timeout, adjust your timeout settings to your preferred duration. If transactions expire before reaching the backend, you may have set the timeout too short or are being rate limited. For long-running transactions, we recommend using asynchronous transactions.
1011	Duplicate Field received
1015	Non Blocking Invalid Field Format	The field which had the formatting issue was dropped and not sent to the specific datasource. The source was still called with the other data.
2000	Unrecognized Error	This is a catchall for other errors - contact Trulioo support for a resolution.
3000	Address Corrected	The address you sent cannot be validated by our address validation service. As a result the uncorrected address information provided in the original request will be sent to all other datasources. This address information may be incomplete or incorrect, which increases the likelihood of receiving a service error from one of the other datasources and reduces the likelihood of receiving a match on address values.
3001	State Province Changed
3002	City Changed
3003	Street Info Changed
3004	Postal Code Changed
3005	Missing Address Info
3008	Cannot validate address
3009	Address validation is not available
4001	Missing Required Field: MobileNumber
4002	Invalid Mobile Number
4003	Mobile Carrier Not Supported

See the Verify documentation for JSON examples of how errors are returned.

Validation Codes

Trulioo includes informational messages about some data sources in each response. These messages aren't always errors; sometimes they notify the developer about validations or corrections the Trulioo system made to the input. However, some codes can indicate why a verification failed, such as an unvalidated address or a blurry image submitted for document verification.

Codes 3001 to 3005 relate to Address Validation. If you haven't enabled address validation and haven't set CleansedAddress = True in your Verify API calls, you won't see these Address Validation Codes in the API response. For more details and examples of data leading to different validation codes, see Address Validation.

Code	Message	Additional Information
3000	Address Verification Level	This error indicates which level provided address was verified to. If any address values were changed or added, the corresponding `3001-3005` validation codes will be returned along with the code `3000`. Address Verification Level can be one of the following: - Fully Validated to unit - Fully Validated to building - Partially Validated to building - Partially Validated to street - Partially Validated to city - Partially Validated to state/province - Address Corrected This code is only visible when reviewing transactions in our API-Direct portal.
3001	State / Province / County changed, please check Address validation fields for additional information	The state/province/region in the provided address was found to be incorrect, given the other address values such as city or postal code, and has been updated to a new value.
3002	One or more of City, Municipality, Suburb have been changed please check Address Validation fields for additional information	The city in the provided address was found to be incorrect, given other address values such as postal code, and has been updated to a new value.
3003	One or more of Unit Number, Building Number, or Street have been changed please check Address Validation fields for additional	The street in the provided address has been updated with a new value based upon the other address data given.
3004	Postal Code changed, please check Address Validation fields for additional information	The postal code in the provided address has been updated with a new value based upon the other address data given.
3005	One or more of Unit Number, Building Number, or Street are either invalid or missing	The street level data for the address is incomplete or invalid and will impact address validation’s ability to validate down to the street, building, or unit level.
3008	Cannot validate address	The address you sent cannot be validated by our address validation service. As a result the uncorrected address information provided in the original request will be sent to all other datasources. This address information may be incomplete or incorrect, which increases the likelihood of receiving a service error from one of the other datasources and reduces the likelihood of receiving a match on address values. This code can be returned both as a datasource level error Trulioo Service/DataSource Level Errors and a record level error Record Level Errors when it occurs.
3100	Blurry Image	Relevant to Document Verification only. When trying to verify a document, image quality is highly important. This error code indicates that the provided image was too blurry to verify. Please retake the image-in-focus and resend the verification request with the new image.
3101	Glare Image	Relevant to Document Verification only. When trying to verify a document, image quality is highly important. This error code indicates that the provided image was too blurry to verify. Please retake the image in good lighting without flash and resend the verification request with the new image. All text on the ID should be readable and not obstructed by a glare spot.
4001	Missing Required Field Mobile Number	Relevant to MobileID only. This error occurs if a mobile number is not present in the request. Make sure that at least one of the Mobile related fields (Mobile Number or Telephone) are entered.
4002	Invalid Mobile Number	Relevant to Mobile ID only. This error occurs if the mobile number entered in the request is not valid. Make sure that the number has been entered correctly and is in the correct format for the given country.
4003	Mobile Carrier Not Supported	Relevant to Mobile ID only. This error occurs if the mobile number entered is from a carrier that is not supported.

Record Level Errors

For issues with the Record itself, (outside of the individual Datasources), Trulioo also communicates record level errors. These types of errors are located within the Errors array for the Record Object:

{
  .
  .
  .
  "Record": {
    "TransactionRecordID": "123456",
    "RecordStatus": "match",
    "DatasourceResults": [*Array of Results*],
    "Errors": [
      {
        "Code": "1002",
        "Message": "Datasource Unavailable - The source did not respond"
      }
    ],
    "Rule": {
      "RuleName": "Rule1",
      "Note": ""
    }
  }
  .
  .
  .
}

Code	Message	Additional Information
1002	Datasource Unavailable	The source did not respond - One of the datasources your account is configured for may have had an error and hasn't responded to Trulioo's request. The support team of Trulioo constantly monitors the datasources for such outages.
1006	Unrecognized Field Name	One or more field names used in your request were not recognized. Possible reasons are that you are using fields from a different country than the one specified in your request, or that there is a simple spelling mistake in the body of the request. Use Get Fields to see which field names are available for a specific country and compare with the request you sent to Trulioo.
1007	Consent Datasource Not Recognized	As explained in the description for Error 1005, if a datasource requires consent, but the provided consent string is in any way different than what's expected, then an Error 1007 is returned. Use Get Consents to get a list of consents needed for a country, and double-check for typos in your request.
1008	Invalid Field Format	The fields in a ‘Verify’ request need to be of a specific data type. For example, ‘FirstGivenName’ must be a UTF-8 string and DayOfBirth must be an Integer. This error may be thrown at Datasource Level or Record Level. Use Get Fields to see the data type of every field in a specific country.
1011	Duplicate Field received	There may have been a copy paste error or a bug that generated an input field twice. Simply remove the second value and resend the request.
2000	Unrecognized Error	This is a catchall for other errors. Please contact Trulioo support for a resolution.
3008	Cannot validate address	The address you sent cannot be validated by our address validation service. As a result the uncorrected address information provided in the original request will be sent to all other datasources. This address information may be incomplete or incorrect, which increases the likelihood of receiving a service error from one of the other datasources and reduces the likelihood of receiving a match on address values.

Get Transaction Record Errors

For the Get Transaction Record call we record errors slightly differently:

"Code=2005, Message=You are not authorized to view this transaction"

Code	Message	Additional Information
2004	Transaction Not Available	Trulioo was not able to find a transaction for the ID you provided. Ensure the ID is a TransactionRecordID (as opposed to TransactionID) and is correct.
2005	Authentication Error	The account that ran the original transaction is not the same as the account running this request. Ensure you are using the same credentials as the account that ran the verify request you are looking for.