Verify Error Codes

The following details all the possible values that can be returned in the status and failureCode fields, when verifying a bank account and what steps to take based on the retunred value.

Verification and status codes

When you verify a bank account, the response details the the result of the verification.

{
    "id": "6a497525-b8b8-45a7-a2fe-6937907c8179",
    "accountHolderName": "HARRY POTTER",
    "currency": "GBP",
    "country": "GB",
    "externalId": "4438e362-c6ec-4b48-8883-133d9dc575cc",
    "status": "invalid",
    "failureCode": "inactive_account",
    "date": "2025-05-21T07:55:13.010Z"
}

For most requests, status returns:

Status	Description	Recommended action
valid	The account exists and the verification was successful. Responses with this status can include derivedAccountDetails providing the account holder's name.	You can resume with your workflow.
invalid	Details can't be validated.	Review and confirm the provided account details and resubmit the request. If the account details are accurate and returns invalid, see the failureCode field to understand why verification failed. .

Specific Failure Codes

When the status of the response is invalid, the failureCode field returns a more granular reason for the failure. Available failure codes include:

Status	Description	Recommended action
invalid_name	The provided accountHolderName does not match the name associated with the account.	Provide this information to your customer and ask them to verify their information and resubmit as needed.
inactive_account	The bank account associated with the provided details is currently inactive.	Provide this information to your customer and ask them to check with their bank or submit details for an active bank account.

General error codes

In addition to verification statuses, Nium Verify requests return standard HTTP status codes for general API errors:

Error are returned in the following structure:

{
    "errors": [
        {
            "code": "invalid_verification_id",
            "description": "invalid verification id"
        }
    ]
}

These codes help identify problems with the request itself or the service availability. The specific error codes are as follows:

HTTP Status Code	Error Code	Error Description	Recommended Action
400	invalid_request	The request payload is malformed or contains invalid fields.	Review the field and description fields in the response and correct the request format.
403	Forbidden	The client ID or API key is invalid.	Verify that your clientId and API key are correct in the Nium Portal.
403	invalid_client	Your client ID is not enabled for Nium Verify.	Contact your Nium account manager or Nium Support to request access.
404	invalid_verification_id	The verificationId does not match any existing record.	Confirm that the verificationId in your request is valid.
422	bank_code_not_supported	The selected bank is not supported for real-time verification.	This bank may not be part of Nium’s verification network. Contact your Nium account manager or Nium Support for supported banks.
422	country_currency_not_supported	The country and currency combination is not supported for verification.	See the supported corridors and use a valid combination.
500	internal_error	A server-side error occurred.	Retry the request. If the issue persists, contact your Nium account manager or Nium Support.