API Management

x-trulioo-api-key Sign Up to get your API key

Errors


There are two types of errors you may encounter when using Trulioo's API: HTTP network errors, and Trulioo service errors. An HTTP error indicates that the request could not be properly handled by the server due to client, network, or server issues. A Trulioo service error means that the request was received and handled correctly, but something went wrong when trying to achieve an identity verification result. This could be caused by a missing required field, a datasource outage, or more (see "Service Errors" below).

HTTP errors

The API uses standard HTTP response codes to indicate the status of a request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate that a failure occurred due to the content or structure of the request (e.g., a required parameter was omitted, the authentication header is missing, etc.), and codes in the 5xx range indicate a server error on Trulioo's part. 5xx errors are rare, and should be handled by emailing Trulioo support. Here are some troubleshooting tips for the more common 4xx errors:

400 BadRequest

Your request could not be processed, details should be included in the body of the response. Some example causes of a 400 BadRequest are:

MessageTroubleshooting

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.

Configuration name not valid

For now, you should always send "Identity Verification" for the configuration name parameter.

Unable to find account

Email Trulioo support to ensure there are no issues with your account.

Transaction not available

Make sure that you are sending the correct TransactionRecordID and that the verification request was sent from this same account.

Account not configured for this country.

Try the Get Country Codes request to see the countries you are configured for.

401 Unauthorized

The user name and password you provided is not valid or you are using an account that does not have API permissions. Make a call to Test Authentication with your username/password in the Authentication header. If you do not see your username echoed back at you, you are using the incorrect password or account.

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.

DataSource Level Errors

Datasource 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.

These types of errors are located within the "Errors" array for a specific DatasourceResult Object:

JSON


        {
          .
          .
          .
            "DatasourceResults": [
              {
                "DatasourceName": "Credit Agency",
                "DatasourceFields": [],
                "AppendedFields": [],
                "Errors": [
                    {
                    "Code": "1001",
                    "Message": "Missing required field: FirstSurName"
                  },
                  {
                    "Code": "1005",
                    "Message": "Missing Consent"
                  }
                ],
                "FieldGroups": []
              },

            ],
                .
                .
                .
        }
        

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. Trulioo's support team is constantly monitoring 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. For example, the following table shows what the required fields might be for 2 separate datasources:

Credit AgencyConsumer

FirstGivenName

FirstSurName

FirstSurName

Gender

DayOfBirth

MonthOfBirth

YearOfBirth

Using these example datasources, if your request only had FirstSurName and Gender values then you would get a 1001 error for the Credit Agency, but you would still get a full response from the Consumer datasource. If you sent only FirstSurName and DayOfBirth, you would get an error from both. Trulioo recommends sending as many of the required fields as possible to optimize your results.

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. Trulioo's support team is constantly monitoring datasources for such outages.

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.

1003 Datasource Error - The source returned an error

One of the datasources your account is configured for has returned an error in response to Trulioo's request. This happens on occasion and Trulioo's support team is constantly monitoring datasources for such errors. The vendor of that particular datasource will be contacted to understand and fix the issue.

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.

1004 State not supported

Relevant to datasource AU 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 for a specific country.

Due to the nature of some of our datasources you may need to acquire 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. It will be a simple list of strings, as in the following example for Australia:

JSON


        [
          "Birth Registry",
          "Visa Verification",
          "DVS ImmiCard Search",
          "DVS Citizenship Certificate Search",
          "Credit Agency"
        ]
        

Note that for a Verify request if the string values do not match exactly those from Get Consents a 1007 error will be returned as detailed below. If a datasource requires a consent acknowledgment but does not receive it, then a verification request will not be sent to that specific datasource.

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. Note, this error may be thrown at Datasource Level or Record Level. Use Get Fields to see the data type of every field for a specific country.

1010 Request Timed Out

On 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. Trulioo's API offers an asynchronous option, so if you are worried about receiving a 1010 error, it is recommend 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.

2000 Unrecognized Error

This is a catch-all for other errors. Please contact Trulioo support for a resolution.

Validation Codes

Trulioo also provides information-level messages about some datasources in each response. These should not be considered errors, as they are only returned to notify the developer about validations or corrections Trulioo's system may have carried out on the input.
Currently, all of our validation codes relate to address cleansing. If you don't have address cleansing enabled you will not see any of these validation codes.

3000 Address Corrected

The address sent has had information either added or updated. This updated address will be sent to all other datasources that accept address information.

3001 State Province Changed

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 City Changed

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 Street Info Changed

The street in the provided address has been updated to a new value.

3004 Postal Code Changed

The postal code in the provided address has been updated to a new value.

3005 Missing Address Info

3008 Cannot validate address

The address you sent cannot be validated by our address cleansing 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.

Record Level Errors

For issues with the Record itself, i.e. 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:

JSON


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

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. Trulioo's support team is constantly monitoring 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.

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 a 1007 error will be 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. Note, this error may be thrown at Datasource Level or Record Level. Use Get Fields to see the data type of every field for a specific country.

1011 Duplicate Field received

There may have been a copy paste error or bug that generated an input field twice. Simply remove the second value and resend the request.

2000 Unrecognized Error

This is a catch-all for other errors. Please contact Trulioo support for a resolution.

3008 Cannot validate address

The address you sent cannot be validated by our address cleansing 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

For the GetTransactionRecord call we record errors slightly differently:

JSON


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

2004 Transaction Not Available

GlobalGateway wasn't 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.