Error Codes
Welcome to Nextra! This is a basic docs template. you can use it as a starting point for your own docs site.
This page lists all possible error responses from the AdmasPay API. Use the error code to identify and handle specific errors in your integration.
HTTP Status Code Reference
Initiate Transaction & Accept Payment
Errors that may occur when initiating a payment transaction
| Status | Code | Message | Description |
|---|---|---|---|
| 401 | - | - | Authorization header is missing or invalid |
| 400 | invalid-api-key | Invalid api key | The provided API key is invalid or expired |
| 400 | missing-mandatory-value | The field "field_name" is mandatory and wasn't set | A required field is missing from the request body |
| 400 | currency-not-found | Failed to find currency | The specified currency code is not supported |
| 415 | - | - | Unsupported Media Type - ensure Content-Type is application/json |
| 400 | transaction-reference-exists | Transaction reference already exists | The txn_ref has already been used. Use a unique reference for each transaction |
Verify Payment
Errors when verifying a transaction status
| Status | Code | Message | Description |
|---|---|---|---|
| 401 | - | - | Authorization header is missing or invalid |
| 400 | invalid-api-key | Invalid api key | The provided API key is invalid or expired |
| 404 | transaction-not-found | Transaction not found | No transaction found with the given reference |
| 400 | transaction-pending | Transaction is pending | The transaction has not been completed by the customer yet |
Direct Payment
Errors specific to direct payment integration
| Status | Code | Message | Description |
|---|---|---|---|
| 401 | - | - | Authorization header is missing or invalid |
| 400 | invalid-api-key | Invalid api key | The provided API key is invalid or expired |
| 400 | missing-mandatory-value | The field "field_name" is mandatory and wasn't set | A required field is missing from the request body |
| 400 | currency-not-found | Failed to find currency | The specified currency code is not supported |
| 415 | - | - | Unsupported Media Type - ensure Content-Type is application/json |
| 400 | customer-account-number-too-long | Account number too long | The phone number or account number exceeds the maximum length |
| 400 | payment-method-not-found | Failed to find the payment method | The payment_method_code is invalid or not supported |
Bank Transfer
Errors when initiating bank transfers
| Status | Code | Message | Description |
|---|---|---|---|
| 401 | - | - | Authorization header is missing or invalid |
| 400 | invalid-api-key | Invalid api key | The provided API key is invalid or expired |
| 400 | payment-method-not-found | Failed to find payment method | The specified bank code is not supported |
| 400 | insufficient-balance | Insufficient balance | Your merchant account balance is insufficient for this transfer |
List Transactions
Errors when fetching transaction history
| Status | Code | Message | Description |
|---|---|---|---|
| 401 | - | - | Authorization header is missing or invalid |
| 400 | invalid-api-key | Invalid api key | The provided API key is invalid or expired |
Payment Methods
Errors when fetching available payment methods
| Status | Code | Message | Description |
|---|---|---|---|
| 401 | - | - | Authorization header is missing or invalid |
| 400 | invalid-api-key | Invalid api key | The provided API key is invalid or expired |
Best Practices for Error Handling
Always check the HTTP status code - Use it to determine the general category of the error before parsing the response body.
Use the error code for specific handling - The code field provides a machine-readable identifier for programmatic error handling.
Display user-friendly messages - Use the message field to show appropriate feedback to your users.
Log errors for debugging - Store the full error response including timestamp for troubleshooting and support requests.
Example Error Response
{
"status": "error",
"code": "invalid-api-key",
"message": "Invalid api key",
"data": null
}