Skip to main content
The meCash API uses standard HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided, and codes in the 5xx range indicate an error with meCash’s servers.

​
meCash API Response Codes

​
Success (2xx)

200 OK

The request was processed successfully. Always examine the response data object to determine the specific outcome (e.g., successful or failed transaction).

201 Created

A new resource was created successfully through your request. This typically occurs when creating new entities like Payouts or Virtual Accounts.

​
Client Errors (4xx)

400 Bad Request

The request failed due to invalid or missing required parameters. Double-check your JSON payload format and required fields.

401 Unauthorized

Authentication failed. This could be caused by an invalid or missing x-api-key in the header. Ensure you are using the correct key for the environment (Sandbox/Production).

403 Forbidden

The API key doesn’t have permissions or the IP is not whitelisted. Check Developers → IP Whitelisting in your dashboard.

404 Not Found

The requested resource does not exist. Verify the endpoint URL or the ID of the resource you are trying to access.

422 Unprocessable Entity

The request was well-formed but could not be followed due to semantic errors (e.g., an expired Quote ID or invalid recipient details).

429 Too Many Requests

The API received too many requests in a short period. Implement exponential backoff for your retries.

​
Server Error (5xx)

500, 502, 503, 504

These codes indicate errors on meCash’s servers. While uncommon, please report any instances to support@me-cash.com.

​
Error Handling Strategies

​
General Error Handling

Check the status field

All meCash responses contain a top-level status field. If it is error, check the errorCode for the specific cause.

Rely on Webhooks

For asynchronous operations like Payouts, the initial API response might be 200 OK (PENDING), but the final outcome is communicated via webhooks.

Use Idempotency

When retrying requests (especially after network failures), use unique reference numbers to prevent duplicate transactions.

​
Specific Error Types

When the API returns an error, the errorCode field provides specific context.
Description: Your wallet does not have enough funds to complete the transaction. Fix: Fund your wallet via the dashboard or a mobile money collection before retrying.
Description: The quoteId provided is invalid, expired, or has already been used. Fix: Quotes typically expire after a few minutes. Generate a new quote and use the fresh quoteId.
Description: One or more parameters in the request body are missing or malformed. Fix: Refer to the endpoint’s request body schema and verify all required fields.
Description: A transaction with the same reference number already exists. Fix: Ensure each transaction has a unique reference, or if retrying a failure, verify if the first attempt succeeded.
Description: We could not verify the recipient’s bank account details. Fix: Double-check the account number and bank code. Use the Account Enquiry endpoint to verify details beforehand.
Description: The specified currency is not supported for this operation or corridor. Fix: Check our Supported Currencies guide for the available routes.