Skip to main content
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

HTTPDescriptionSuggested Action
400The request is invalid (e.g. malformed JSON or missing fields).Check your request payload against the schema.
401Authentication failed or token expired.Refresh your access token via /oauth2/token.
403You have reached your credit limit or lack permissions.Top up your account or check your subscription status.
404The requested resource (Verification ID) does not exist.Verify the UUID provided in the URL.
429Rate 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_reasonMeaningRecommended Action
institution_timeoutThe 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_scopeThe bank is not yet reachable for account holder verification.Do not retry.

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