Skip to main content
When a request fails, the iDenfy API responds with the appropriate HTTP status code and a JSON body: 
{
  "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

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.

​
POST /api/v2/token Errors

​
Authentication Errors

These occur before any request processing and result in a non-200 response with no identifier field.
StatusMessageWhen
401"Invalid authorization credentials"Missing or incorrect API key / secret
403"Partner inactive"Partner account is disabled
403"This endpoint is not available for {ENV} partners."Wrong environment (e.g. test credentials used against production)
402"Action not allowed due to lack of funds or exceeded limit."Insufficient balance or expense limit exceeded

​
Request Parsing Errors

StatusMessageWhen
400"An error occurred while parsing/constructing JSON"Request body is empty
400"Invalid data. Expected a dictionary, but got {type}."Body is an array or string instead of an object
400"Some of required values are missing"Body is null

​
Field Validation Errors

All field validation errors return HTTP 400.
FieldValidation rule
clientIdRequired. Maximum 100 characters.
expiryTimeMust be an integer greater than 0 and no more than 2,592,000 seconds (30 days).
sessionLengthInteger between 60 and 3,600 seconds.
tokenTypeMust be one of the supported enum values.
countryISO 3166-1 alpha-2 format; must be a supported country.
documentsMust be an array; each item must be a valid document type.
successUrl / errorUrl / callbackUrl / unverifiedUrlMust be a valid HTTPS URL, maximum 2,048 characters.
dateOfBirth / dateOfExpiry / dateOfIssueMust follow YYYY-MM-DD format.
nationalityISO 3166-1 alpha-2 format; must be a supported country.

​
Business Logic Errors

All business logic errors return HTTP 400.
Scenario
Country and document type combination is not supported
Partner is not allowed to generate the requested token type
Custom callback URL is not enabled for this partner
additionalSteps is not enabled for this partner
utilityBill and additionalSteps used together — use additionalSteps only
address and additionalData used together
generateDigitString=true but expiry time exceeds the mobile code maximum
Invalid questionnaire ID or risk assessment profile ID

​
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']}")