Errors
Last updated October 6th, 2026
Error Types
When you make an API call to our endpoints, Mono uses conventional HTTP response codes to indicate the success or failure of the API request. In general, codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that occurred due to the information provided, for example, a required parameter was omitted. Codes in the 5xx range indicate an error with our servers, but these are usually rare.
Below, we have detailed API errors you might encounter using Mono and how to fix them. For widget errors, please get in touch with our support team here.
API Error Codes
| Code | Type | What it means |
200 | OK | Everything worked as expected. |
400 | Bad request | The request was not accepted, often due to missing a required parameter. |
401 | Unauthorised | No valid API key provided. |
402 | Request Failed | The request was unacceptable, often due to missing a required parameter. |
403 | Forbidden | The API key doesn’t have permissions to perform the request. |
404 | Not Found | The requested resources doesn’t exist. |
409 | Conflict | The request conflicts with another request (perhaps due to using the same idempotent key). |
429 | Too Many Requests | Too many requests hit the API too quickly. We recommend an exponential backoff of your request. |
500 502 503 504 | Server Errors | Something went wrong on Mono’s end. (These are rare). |
Direct Debit Error Codes
| Code | Type | What it means |
01 | Direct Debit | Status unknown, please wait for settlement report. |
03 | Direct Debit | Invalid Sender. |
05 | Direct Debit | Do not honor. Originating bank issue. |
06 | Direct Debit | Dormant Account |
07 | Direct Debit | Invalid Account |
08 | Direct Debit | Account Name Mismatch |
09 | Direct Debit | Request processing in progress |
12 | Direct Debit | Invalid transaction |
13 | Direct Debit | Invalid Amount |
14 | Direct Debit | Invalid Batch Number |
15 | Direct Debit | Invalid Session or Record ID |
16 | Direct Debit | Unknown Bank Code |
17 | Direct Debit | Invalid Channel |
18 | Direct Debit | Wrong Method Call |
21 | Direct Debit | No action taken |
25 | Direct Debit | Unable to locate record. Originating bank issue. |
26 | Direct Debit | Duplicate record |
30 | Direct Debit | Format error |
34 | Direct Debit | Suspected fraud |
35 | Direct Debit | Contact sending bank |
51 | Direct Debit | Insufficient funds |
57 | Direct Debit | Transaction not permitted to sender |
58 | Direct Debit | Transaction not permitted on channel |
61 | Direct Debit | Transfer limit Exceeded. Returned when a credit amount exceeds the daily limit allowed on the beneficiary account |
63 | Direct Debit | Security violation |
65 | Direct Debit | Exceeds withdrawal frequency |
68 | Direct Debit | Response received too late |
69 | Direct Debit | Unsuccessful Account/Amount block |
70 | Direct Debit | Unsuccessful Account/Amount unblock |
91 | Direct Debit | Beneficiary Bank not available |
92 | Direct Debit | Routing error |
94 | Direct Debit | Duplicate transaction |
97 | Direct Debit | Timeout waiting for response from destination |
m01 | Direct Debit | Timeout or downtime from NIBSS |
a6 | Direct Debit | Mandate not approved by bank |
Direct Debit Widget Errors, Meanings, and Next Steps
| Error Message | Meaning | Next step |
| The link is already used and the mandate setup is completed | The mandate setup link has already been used to complete the mandate setup. | No further action is required. If a new mandate needs to be created, generate a new link. |
| The start date is already in use for an existing mandate | There is an existing mandate on the account with the same start date that has not yet been approved. | Select a different start date and try again. |
| Mono Sweep could not be set up because no supported linked accounts were found | There are no eligible linked accounts available to set up the Sweep mandate. | Ensure the customer has a supported linked account and try again. |
| Unable to fetch BVN details | We were unable to retrieve the BVN details. This may be due to a temporary service issue. | Try again later. |
| RC number does not match the account name, please check and try again | The RC number provided does not match the business name associated with the account. | Check the RC number and account details, then try again. |
| We couldn't find any matching records based on the information you provided. Please double-check the parameters you passed and try again | The RC number provided is either invalid or does not belong to the business. | Enter the correct RC number registered to the business and try again. |
| We couldn't find any matching records based on the information you provided | No business records were found that match the information provided. | Double-check the RC number and other business details, then try again. |
| BVN name mismatch with business shareholders | For mandates created on a business account, the authorizer's BVN details must match an active shareholder of the business. | Ensure the authorizer is an active shareholder of the business and try again. |
Error Handling
While building your Mono integration, we strongly recommend that you keep a log of all API requests you make and the responses you receive. You should keep a log file as part of your application and record the API signature, any API URL parameters, and request body (you may strip the API keys) in JSON. Then, write down the API response code and log the JSON body of the error message if one occurs. When your integration is stable, you can lower the logging level and log only the API name (signature), the response code, and any error messages that may have occurred.
On your Mono dashboard, you can also see the logs of each API call you make. This applies to both successful and failed responses (provided the access key and secret key are correct).
To access your API Logs on the dashboard:
- Log in to the Mono dashboard and navigate to Audit Logs > API Logs.
- Use the dropdown at the top right to select your Mono App, or filter by Scope (Identity, Statements, etc), Status (failed or successful), and Environment (live or test).
- Then, your API call data will be displayed based on the filters you chose.
In addition, the response body will be empty if a standard HTTP error code such as 401 (Not Authorized) or 404 (Not Found) is sufficiently descriptive. The response will also contain an error entity that provides additional information about the incident, including an application error code and a human-readable error description. In other situations, we will utilize the standard response code for client errors (400).