> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.idenfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```json theme={"system"}
{
  "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

<AccordionGroup>
  <Accordion title="&#x22;Partner reached token limit&#x22;">
    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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Example Error Handling

<CodeGroup>
  ```python Python theme={"system"}
  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']}")
  ```

  ```javascript JavaScript theme={"system"}
  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}`);
  }
  ```
</CodeGroup>