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.

CodeMessageAdditional Information
4000Flow not foundThe flow ID isn’t valid, meaning the flow either hasn’t been published or has been deleted
4001Flow theme not foundThe theme you’ve set for your hosted workflow doesn’t exist
4002Node not foundThe workflow step you’re trying to access does not exist within the workflow
4003Flow is empty
4005Root node
4006Missing data for required elementThe data for a required form field has not been sent
4007Submitted data is malformedData does not match the input format for that field

Examples:
Text was submitted in a number only field
Input was submitted on a Regex field
4008Failed validation for submitted data
4009Service execution failedThe Trulioo service you’ve called in the workflow has returned an error.
4011Invalid token
4012Flow already finishedThe hf_session is linked to a workflow that shows a completed status which means the workflow you’re trying to call has already completed
This usually happens after you’ve initialized a workflow that has completed
4013Token has expired
4014Invalid submit data
4050Invalid credentials
4100Client not foundThe Client ID is pointing to an account that doesn’t exist
4101Client has no flow with given IDHow does this differ from Error 4000 above?
4102Subsequent token not found
4103Illegal back action
4200Service not configuredTrulioo service has not been activated.
4201Service not configured for countryTrulioo service has not been assigned to a country.
5300Invalid Twilio codeThe code you’re using to access the Twilio model is invalid. Contact our Support Team
5301Failed to send SMS to phone numberThe phone number you’ve tried to text didn’t work is there more?
5302Twilio internal errorAccessing the Twillio Service in the workflow returned an error. Contact our Support Team.
6504Service has timed outThe service hasn’t returned data within the expected timeframe

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.

CodeMessageTroubleshooting
400 BadRequest -Account not configured for this productEnsure you are configured properly with the Get Country Codes request to see the countries you are configured for.
400 BadRequest -Configuration name not validFor now, you should always send "Identity Verification" for the configuration name parameter.
400 BadRequest -Unable to find accountEmail Trulioo support to ensure there are no issues with your account.
400 BadRequest -Transaction not availableMake 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.
401UnauthorizedThe 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
413Request Entity Too LargeIf the request you sent is over the current limit.
415UnsupportedMediaTypeYou asked for a media type that we do not support. Make sure your request includes a Content-Type: application/json header.
500ErrorAn error happened on the server without a specific message. These are very rare, and should be handled by emailing Trulioo support.
500Configuration name not validFor now, you should always send "Identity Verification" for the configuration name parameter.
409ErrorThe API requests have gone over the limit set for your account (not applicable for Enterprise users).
403ErrorThe API key provided is invalid or expired.
404ErrorCannot 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.

CodeMessageAdditional Information
1000Provider Error - There was an error connecting to the sourceOne 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.
1001Missing Required FieldBy 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.
1002Datasource Unavailable - the source did not respondThis 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.
1003Datasource Error - The source returned an errorThis 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.
1004State 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.
1005Missing consent - consent not sent for the sourceDue 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.
1006Unrecognized Field Name
1008Invalid Field FormatThe 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.
1009Unrecognized Field group
1010Request Timed OutOn rare occasions, Trulioo will be unable to respond in the usual time window and will return this error code. This may be due to networking issues, or other reasons. The API from Trulioo offers an asynchronous option, so if you are worried about receiving a 1010 error, it is recommended to set a high timeout value in the ‘Verify’ request call. This will do two things:

1. Set the call to be asynchronous and
2. Make sure the request only times out once the value you have set is met.
1011Duplicate Field received
1015Non Blocking Invalid Field FormatThe field which had the formatting issue was dropped and not sent to the specific datasource. The source was still called with the other data.
2000Unrecognized ErrorThis is a catchall for other errors - contact Trulioo support for a resolution.
3000Address CorrectedThe 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.
3001State Province Changed
3002City Changed
3003Street Info Changed
3004Postal Code Changed
3005Missing Address Info
3008Cannot validate address
3009Address validation is not available
4001Missing Required Field: MobileNumber
4002Invalid Mobile Number
4003Mobile 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.

CodeMessageAdditional Information
3000Address Verification LevelThis 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.
3001State / Province / County changed, please check Address validation fields for additional informationThe 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.
3002One or more of City, Municipality, Suburb have been changed please check Address Validation fields for additional informationThe 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.
3003One or more of Unit Number, Building Number, or Street have been changed please check Address Validation fields for additionalThe street in the provided address has been updated with a new value based upon the other address data given.
3004Postal Code changed, please check Address Validation fields for additional informationThe postal code in the provided address has been updated with a new value based upon the other address data given.
3005One or more of Unit Number, Building Number, or Street are either invalid or missingThe 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.
3008Cannot validate addressThe 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.
3100Blurry ImageRelevant 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.
3101Glare ImageRelevant 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.
4001Missing Required Field Mobile NumberRelevant 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.
4002Invalid Mobile NumberRelevant 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.
4003Mobile Carrier Not SupportedRelevant 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": ""
    }
  }
  .
  .
  .
}
CodeMessageAdditional Information
1002Datasource UnavailableThe 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.
1006Unrecognized Field NameOne 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.
1007Consent Datasource Not RecognizedAs 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.
1008Invalid Field FormatThe 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.
1011Duplicate Field receivedThere 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.
2000Unrecognized ErrorThis is a catchall for other errors. Please contact Trulioo support for a resolution.
3008Cannot validate addressThe 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"
CodeMessageAdditional Information
2004Transaction Not AvailableTrulioo 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.
2005Authentication ErrorThe 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.