Skip to main content
When a request fails, the iDenfy API responds with HTTP 400 (or the appropriate status code) and a JSON body containing two fields: 
{
  "identifier": "BAD_VALUE",
  "message": "Field 'country' must be a valid ISO 3166-1 alpha-2 code."
}
FieldDescription
identifierA constant error code you can match on programmatically.
messageA human-readable explanation of what went wrong.

​
Error identifiers

​
identifier
string
One of the values listed below.
IdentifierMeaning
INTERNAL_ERRORAn unexpected error on the iDenfy side. Retry the request or contact support if it persists.
BAD_VALUEA request parameter has an invalid value. Check the message field for details.
MISSING_VALUEA required parameter is missing from the request.
UNAUTHORIZEDInvalid or missing API credentials. Verify your API key and secret.
ENCODING_ERRORThe request body could not be decoded. Ensure it is valid UTF-8.
JSON_ERRORThe request body is not valid JSON.
TOKEN_NOT_VALIDThe verification token is expired, already used, or does not exist.
PARTNER_CONTRACT_ERRORYour account contract does not permit this operation. Contact your account manager.
METHOD_NOT_ALLOWEDThe HTTP method is not supported for this endpoint (e.g., GET instead of POST).
PERMISSIONS_ERRORYour account does not have permission for the requested resource or action.
TOO_MANY_REQUESTSYou have exceeded the rate limit. The default limit is 10,000 requests per hour.
VALIDATION_ERROROne or more fields failed validation. Inspect the message for specifics.

​
Common issues

This error means your account has run out of verification credits. It is not a rate-limit issue. Contact your iDenfy account manager to purchase additional credits or upgrade your plan.
The default rate limit is 10,000 requests per hour. If you need a higher limit, contact iDenfy support. Implement exponential back-off in your integration to handle transient rate-limit responses gracefully.
  • Verify that your API key and secret have not been rotated in the dashboard.
  • Check that you are sending credentials in the correct format (HTTP Basic Auth with base64 encoding).
  • Ensure there is no trailing whitespace in your stored credentials.

​
Example error handling

import requests

response = requests.post("https://ivs.idenfy.com/api/v2/token", json=payload, auth=(API_KEY, API_SECRET))

if response.status_code != 200:
    error = response.json()
    print(f"Error [{error['identifier']}]: {error['message']}")