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

HTTPCodeDescriptionSuggested Action
400ERROR_CODE_BAD_REQUESTThe request is invalid (e.g. malformed JSON or missing fields).Check your request payload against the schema.
401ERROR_CODE_UNAUTHORIZEDAuthentication failed or token expired.Refresh your access token via /oauth2/token.
403ERROR_CODE_ACCESS_DENIEDYou have reached your credit limit or lack permissions.Top up your account or check your subscription status.
404ERROR_CODE_NOT_FOUNDThe requested resource (Verification ID) does not exist.Verify the UUID provided in the URL.
429ERROR_CODE_TOO_MANY_REQUESTSRate 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. 
{
  "code": "ERROR_CODE_BAD_REQUEST",
  "message": "IBAN must be provided"
}

​
Common Errors

​
400 Bad Request

Missing required field: 
{
  "code": "ERROR_CODE_BAD_REQUEST",
  "message": "The 'iban' field is required within 'account' object."
}
Invalid IBAN format: 
{
  "code": "ERROR_CODE_BAD_REQUEST",
  "message": "Invalid IBAN format: must start with 2 letters followed by 13–32 alphanumeric characters"
}
Action: Validate IBAN client-side before sending.

​
401 Unauthorized

{
  "code": "ERROR_CODE_UNAUTHORIZED",
  "message": "Invalid token"
}
Causes:
  • Token expired (>1 hour old)
  • Invalid client_id or client_secret
  • Token not included in Authorization header
Action: Request new access token.

​
403 Forbidden

{
  "code": "ERROR_CODE_ACCESS_DENIED",
  "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": "ERROR_CODE_TOO_MANY_REQUESTS",
    "message": "Too many requests. 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
responding_institution_timeoutThe bank did not respond within the timeframe.Retry once after 30 seconds.
institution_out_of_scopeThe bank is not yet reachable for account holder verification.**Do not retry. **
We recommend a manual verification.
verification_not_possibleGeneric error or specific bank restriction.**Do not retry. **
We recommend a manual verification.