Error Handling

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:

{
  "code": "iban_required",
  "message": "The IBAN field is required within account object."
}

Action: Ensure the IBAN is provided in the request.
Invalid IBAN format:

{
  "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:

{
  "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:

{
  "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:

{
  "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

{
  "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

{
    "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. 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. 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. We suggest proceeding with a manual verification.

Getting started

Core concepts

Authentication

IBAN Holder Verifications

Bulk Verifications

Sandbox

1. API Errors

HTTP Status Codes

Error Response Format

Common Errors

400 Bad Request

403 Forbidden

429 Rate Limit Exceeded

2. Verification Failures

​1. API Errors

​HTTP Status Codes

​Error Response Format

​Common Errors

​400 Bad Request

​403 Forbidden

​429 Rate Limit Exceeded

​2. Verification Failures

1. API Errors

HTTP Status Codes

Error Response Format

Common Errors

400 Bad Request

403 Forbidden

429 Rate Limit Exceeded

2. Verification Failures