> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payaza.africa/llms.txt
> Use this file to discover all available pages before exploring further.
# Errors
> A reference for all Payaza API error responses, their causes, and how to fix them.
When a Payaza API request fails, the response body contains a descriptive error message. This page lists all common errors by product area, along with their causes and fixes.
The most common causes of errors are: a missing or incorrectly encoded API key, a reused `transaction_reference`, or a mismatch between your key's environment and the `X-TenantID` header.
***
## Authentication errors
```json theme={null}
{
"message": "Authentication failed",
"status": false,
"retry_count": 0
}
```
| Cause | Fix |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Missing or empty `Authorization` header | Add `Authorization: Payaza ` to every request |
| API key not Base64-encoded | Encode your key before use — see the [Authentication guide](/guides/authentication) |
| Wrong prefix (e.g. `Bearer` instead of `Payaza`) | Change the prefix to `Payaza` |
| Test key used with `X-TenantID: live`, or vice versa | Match the key to its environment |
| Key was regenerated on the dashboard | Copy the new key, re-encode it, and update your integration |
***
## Transfer errors
| Error message | Cause | Fix |
| -------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `"Payout amount is less than total credit amount"` | The sum of `credit_amount` values in `payout_beneficiaries` exceeds `payout_amount` | Ensure `payout_amount` equals the sum of all `credit_amount` values |
| `"Insufficient Balance"` | Your Payaza account balance is below the transfer amount | Top up your account or reduce the transfer amount |
| `"Invalid transaction pin"` | The `transaction_pin` in the request body is incorrect | Correct the PIN — see [how to set your PIN](/guides/transfers#step-3) |
| `"Transaction reference already exists"` | A `transaction_reference` was reused | Generate a unique reference for every transfer attempt |
| `"Bank code is not correct"` | The `bank_code` value is invalid | Verify the bank code against the supported bank list |
| `"Account number can only be numbers"` | The `account_number` contains non-numeric characters | Pass only numeric digits |
| `"Account number must be 10 digits"` | The `account_number` is not 10 digits (NGN only) | Pass a valid 10-digit NUBAN number |
**Sample responses**
```json Insufficient balance theme={null}
{
"response_code": 500,
"response_message": "Insufficient Balance"
}
```
```json Invalid PIN theme={null}
{
"response_code": 500,
"response_message": "Invalid transaction pin",
"response_content": {
"message": "Invalid transaction Pin",
"retry_count": 1
}
}
```
```json Duplicate reference theme={null}
{
"response_code": 0,
"response_message": "Transaction reference already exists. please use unique reference",
"resp_code": "X03"
}
```
```json Wrong bank code theme={null}
{
"response_code": 0,
"response_message": "Bank code is not correct for reference: payazaTest",
"resp_code": "X02"
}
```
See the [Transfers guide](/guides/transfers) for the full integration walkthrough.
***
## Virtual Account errors
| Error message | Cause | Fix |
| ---------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `"Transaction not found"` | The `transaction_reference` does not exist | Verify you are using the correct reference |
| `"Reserved Virtual Account does not exist"` | The virtual account number is incorrect or was never created | Check the account number and confirm creation succeeded |
| `"Could not generate virtual account at the moment"` | Upstream network error | Retry the request. If the issue persists, contact [support@payaza.africa](mailto:support@payaza.africa) |
**Sample responses**
```json Transaction not found theme={null}
{
"response_code": 404,
"response_message": "Transaction not found",
"response_content": {
"transaction_reference": ""
}
}
```
```json Reserved VA not found theme={null}
{
"response_code": 404,
"response_message": "Reserved Virtual Account does not exist",
"response_content": {
"page": 0,
"transaction_count": 0,
"virtual_account_number": "960633617",
"virtual_account_name": null,
"virtual_account_status": null,
"virtual_account_provider_bank": null,
"transactions": null
}
}
```
```json Network error theme={null}
{
"response_code": 500,
"response_message": "Could not generate virtual account at the moment, please try again.",
"status": "X02"
}
```
See the [Virtual Accounts guide](/guides/virtual-accounts) for the full integration walkthrough.
***
## Card errors
| Error message | Cause | Fix |
| ------------------------------------------------------------------------------------------ | ----------------------------------- | -------------------------------------------- |
| `"There is already an authentication outcome associated with the supplied transaction ID"` | Duplicate `transaction_reference` | Generate a new unique reference and retry |
| `"Unable to determine card payment"` | Invalid or unsupported card details | Verify the card number, expiry date, and CVV |
| `"Expired card"` | The card's expiry date has passed | Use a valid non-expired card |
**Sample responses**
```json Duplicate reference theme={null}
{
"statusOk": false,
"message": "Transaction Failed",
"debugMessage": "Value 'TEST1213TEST' is invalid. There is already an authentication outcome associated with the supplied transaction ID. To perform another authentication on the order, provide a new transaction ID.",
"waitForNotification": false,
"do3dsAuth": false,
"paymentCompleted": false,
"amountPaid": 0,
"valueAmount": 0
}
```
```json Invalid card details theme={null}
{
"statusOk": false,
"message": "Transaction Failed",
"debugMessage": "Value '401200xxxxxx1111' is invalid. Unable to determine card payment.",
"waitForNotification": false,
"do3dsAuth": false,
"paymentCompleted": false,
"amountPaid": 0,
"valueAmount": 0
}
```
```json Expired card theme={null}
{
"statusOk": false,
"message": "Transaction Failed",
"debugMessage": "Expired card",
"waitForNotification": false,
"do3dsAuth": false,
"paymentCompleted": false,
"amountPaid": 0,
"valueAmount": 0
}
```
Use [Test Cards](/guides/testcards) to simulate different card outcomes during development.
***
## Account Name Enquiry errors
| Error message | Cause | Fix |
| -------------------------------------- | ------------------------------------------- | -------------------------------------------------- |
| `"Bank code should be 6 values"` | `bank_code` is not 6 digits | Pass a valid 6-digit bank code as an integer |
| `"Unknown Bank Code"` | The bank code is not recognized | Verify the code against the supported bank list |
| `"Invalid Account"` | The account number is incorrect or inactive | Double-check the account number with the recipient |
| `"Account number should be 10 values"` | Account number is not 10 digits (NGN only) | Pass a valid 10-digit NUBAN number |
***
## Apple Pay & Google Pay errors
| Error message | Cause | Fix |
| -------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------- |
| `"Kindly check the provided Authorization"` | Invalid or incorrectly formatted API key | Re-encode your key and use the `Payaza ` format |
| `"Transaction Reference already exists"` | Reused `transaction_reference` | Generate a unique reference per transaction |
| `"Payment option can be either GOOGLEPAY or APPLEPAY"` | Invalid `payment_option` value | Pass `"GOOGLEPAY"` or `"APPLEPAY"` exactly |
| `"Payment option is currently not available via this channel"` | Unsupported currency for wallet payments | Use a supported currency code |
| `"Transaction not found"` | The `transaction_reference` does not match any record | Verify the reference is correct |
***
## General tips
Generate a new `transaction_reference` for every request. Reusing a reference is one of the most common causes of errors — especially duplicate-reference errors on transfers and card charges. A UUID or a timestamp-prefixed string works well.
Test keys only work with `X-TenantID: test`. Live keys only work with `X-TenantID: live`. Mismatching them returns an authentication error.
Your raw API key is not valid in the `Authorization` header. It must be Base64-encoded first. See the [Authentication guide](/guides/authentication) for language-specific examples.
Email [support@payaza.africa](mailto:support@payaza.africa) with your `transaction_reference` and the full error response body. The support team can trace the request on their end.