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

# Error Handling

> Handle API errors, failed verifications, and implement retry logic

Ibantrack categorizes issues into two types: **API Errors** (your request failed to process) and **Verification Failures** (the request was valid, but the bank could not verify the IBAN).

## 1.  API Errors

These errors occur when the request is malformed, unauthorized, or hits rate limits. The API returns a JSON response with an error code.

Ibantrack uses standard HTTP status codes and structured error responses.

## HTTP Status Codes

| **HTTP** | **Description**                                                 | **Suggested Action**                                   |
| :------- | :-------------------------------------------------------------- | :----------------------------------------------------- |
| `400`    | The request is invalid (e.g. malformed JSON or missing fields). | Check your request payload against the schema.         |
| `401`    | Authentication failed or token expired.                         | Refresh your access token via `/oauth2/token`.         |
| `403`    | You have reached your credit limit or lack permissions.         | Top up your account or check your subscription status. |
| `404`    | The requested resource (Verification ID) does not exist.        | Verify the UUID provided in the URL.                   |
| `429`    | Rate limit exceeded.                                            | Implement an exponential backoff retry logic.          |

## Error Response Format

When an error occurs, the API returns a JSON response with a specific error code and a human-readable message.

## Common Errors

### 400 Bad Request

\
**Missing required field:**

```json theme={null}
{
  "code": "iban_required",
  "message": "The IBAN field is required within account object."
}
```

**Action:** Ensure the IBAN is provided in the request.

\
**Invalid IBAN format:**

```json theme={null}
{
  "code": "invalid_iban_format",
  "message": "Invalid IBAN format: must start with 2 letters followed by 13–32 alphanumeric characters."
}
```

**Action:** Ensure the IBAN is correct and complete before submitting the request.

\
**Invalid IBAN format for country:**

```json theme={null}
{
  "code": "invalid_iban_format_for_country",
  "message": "Invalid IBAN format: incorrect IBAN length for country FR (expected: 27, received: 26)."
}
```

**Action:** Ensure the IBAN is correct and complete before submitting the request.

\
**Invalid IBAN checksum:**

```json theme={null}
{
  "code": "invalid_iban_checksum",
  "message": "Invalid IBAN format: checksum validation failed."
}
```

**Action:** Ensure the IBAN is correct and complete before submitting the request.

\
**Invalid name format:**

```json theme={null}
{
  "code": "invalid_name_format",
  "message": "Invalid name format: maximum 140 characters, only letters, digits, spaces and / - ? : ( ) . , ' + are allowed, accented characters are not supported."
}
```

**Action:** Ensure the name follows the allowed character and length rules before submitting the request.

### 403 Forbidden

```json theme={null}
{
  "code": "insufficient_credits",
  "message": "You have reached your credit limit. Please top up your account to continue using the service."
}
```

**Action:** Add credits in Ibantrack Dashboard.

### 429 Rate Limit Exceeded

```json theme={null}
{
    "code": "rate_limit_exceeded",
    "message": "Too many requests have been sent in a given amount of time. Please try again later."
}
```

**Limits:**

* POST `/account-holder-verifications`: 60 req/min
* GET `/account-holder-verifications/{id}`: 120 req/min

**Action:** Pause & Retry. Implement exponential backoff. Do not retry more than 5 times.

## 2. Verification Failures

A verification can return a `200 OK` HTTP code but have a `status: "failed"`.

This means your API call was successful, but the banking network could not perform the check.

When `status` is `failed`, use the `status_reason` to have additional context about the failure:

| `status_reason`             | Meaning                                                                                                                                                                                       | Recommended Action                                                                                                                                                            |
| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `institution_timeout`       | The banking institution did not respond within the permitted timeframe.  This is usually caused by temporary maintenance or a high volume of requests on the interbank network.               | **Wait at least 1 minute before retrying.** <br /><br />If the error persists after 3 attempts, the responding institution's services may be undergoing extended maintenance. |
| `institution_out_of_scope`  | The bank is not yet reachable for account holder verification.                                                                                                                                | **Do not retry.**<br /><br />We suggest proceeding with a manual verification.                                                                                                |
| `verification_not_possible` | The service was unable to obtain a response from the banking institution. This may be due to a specific restriction applied to this account by the bank, or a temporary service interruption. | **Do not retry.**<br /><br />We suggest proceeding with a manual verification.                                                                                                |