ID Error Messages

Reference for iDenfy KYC API error codes, including token endpoint validation errors, HTTP response formats, and troubleshooting guidance.

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."
}

Field	Description
identifier	A constant error code you can match on programmatically.
message	A human-readable explanation of what went wrong.

Error Identifiers

Identifier	Meaning
INTERNAL_ERROR	An unexpected error on the iDenfy side. Retry the request or contact support if it persists.
BAD_VALUE	A request parameter has an invalid value. Check the message field for details.
MISSING_VALUE	A required parameter is missing from the request.
UNAUTHORIZED	Invalid or missing API credentials. Verify your API key and secret.
ENCODING_ERROR	The request body could not be decoded. Ensure it is valid UTF-8.
JSON_ERROR	The request body is not valid JSON.
TOKEN_NOT_VALID	The verification token is expired, already used, or does not exist.
PARTNER_CONTRACT_ERROR	Your account contract does not permit this operation. Contact your account manager.
METHOD_NOT_ALLOWED	The HTTP method is not supported for this endpoint (e.g., GET instead of POST).
PERMISSIONS_ERROR	Your account does not have permission for the requested resource or action.
TOO_MANY_REQUESTS	You have exceeded the rate limit. The default limit is 10,000 requests per hour.
VALIDATION_ERROR	One 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.

Status	Message	When
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

Status	Message	When
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.

Field	Validation rule
clientId	Required. Maximum 100 characters.
expiryTime	Must be an integer greater than 0 and no more than 2,592,000 seconds (30 days).
sessionLength	Integer between 60 and 3,600 seconds.
tokenType	Must be one of the supported enum values.
country	ISO 3166-1 alpha-2 format; must be a supported country.
documents	Must be an array; each item must be a valid document type.
successUrl / errorUrl / callbackUrl / unverifiedUrl	Must be a valid HTTPS URL, maximum 2,048 characters.
dateOfBirth / dateOfExpiry / dateOfIssue	Must follow YYYY-MM-DD format.
nationality	ISO 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

"Partner reached token limit"

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.

TOO_MANY_REQUESTS

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.

UNAUTHORIZED on a previously working key

• 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

Python

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

const res = await fetch("https://ivs.idenfy.com/api/v2/token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Basic " + btoa(`${API_KEY}:${API_SECRET}`),
  },
  body: JSON.stringify(payload),
});

if (!res.ok) {
  const error = await res.json();
  console.error(`Error [${error.identifier}]: ${error.message}`);
}