API Errors Reference

tru.ID uses HTTP response status codes to indicate the success or failure of your API request. Additionally, error responses use the RFC 7807 - Problem Details for HTTP APIs standard.

HTTP Response Status Codes Overview

• 2xx your request succeeded.
• 3xx additional action should be taken by the client. The most common use of this code is for redirects.
• 4xx an error occurred due to information in the API request. For example, invalid credential or a missing required parameter.
• 5xx an internal error occurred within the tru.ID platform.

Problem Details for HTTP APIs

4xx error response use Problem Details for HTTP APIs. These take the form:

HTTP/1.1 {status_code} {reason}
Content-Type: application/problem+json

{
"type": {type_url},
"title": {title},
"detail": {detail}
}

The header of the API response contains:

• status_code - the HTTP response status code value.
• reason - a standard HTTP textual reason for the status code.
• Content-Type - the content type header has a value of application/problem+json to indicate the body contents "Problem Details for HTTP APIs" format.

The body of the API response contains:

• type_url - the type property contains value that is a URL for more information on the error that has occurred.
• title - a short descriptive title for the error.
• detail - additional details about the error.

tru.ID HTTP Error Status Codes

Bad Request (400)

An error occurred due to information in the API request. For example, invalid credential or a missing required parameter.

Phone Format Invalid (400)

The provided phone number did not adhere to the E.164 phone number format. The phone number must contain the international country code, the phone number including area code excluding the leading 0.

Mobile Network Operator Not Supported (400)

The Mobile Network Operator (MNO) associated with phone number is not supported.

Unauthorized (401)

The request has unsuccessful because it lacks valid authentication credentials for the target resource.

Access Token Error (401)

An access token is not valid or is not present.

Insufficient Funds (402)

The workspace associated with the API request does not have enough funds to complete the request. Go to the tru.ID console and add funds.

Forbidden (403)

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.

Invalid Scope (403)

The access token used with the API request does not have the required scope to perform the request action. For more information on access token scopes see Create an Access Token.

Not Found (404)

The requested resource does not exist.

Workspace Not Found (404)

The Workspace for the API request could not be found. For example, if an API request is made to create a Project in the US for a Workspace that only exists in the EU.

Check Not Found (404)

The Check with the given check_id does not exist.

Trace Not Found (404)

The Trace with the given trace_id does not exist.

Flow Not Found (404)

The Flow with the given flow_id does not exist.

IP MSISDN Mismatch (409)

Only returned if phone_ip is provided in request body, and if the phone_ip mobile network operator does not match the mobile network operator of the data connection making the request.

Trace Gone (410)

After seven days, the trace is no longer accessible.

Not a Mobile Network IP (412)

The IP address of the device failed a precondition: the IP address should be associated with a cellular connection for a Mobile Network Operator.

The Check URL for a PhoneCheck or SubscriberCheck must be requested over a cellular data connection.

Too Many Requests (429)

The API rate limit for the workspace has been exceeded. The response Retry-After HTTP header will contain a value indicating the number of seconds after which API interactions can be retried.

Internal Server Error (500)

An internal server error occured on the tru.ID platform (these are rare).

Mobile Network Operator Not Responding (504)

We are currently unable to connect to the Mobile Network Operator.

Mobile Network Operator Redirect Not Supported (501)

The Mobile Network Operator (MNO) associated with phone number does not support redirects.