Common MTN MoMo API Errors and How to Fix Them

401 Unauthorized

The most common error during setup. Causes:

• Wrong API key. Double-check that you are using the correct subscription key from the MoMo Developer Portal. Copy-paste errors are common.
• Expired access token. MoMo tokens expire after a set period. Your code should handle token refresh automatically. If you are getting 401 on API calls that previously worked, your token has likely expired.
• Sandbox vs production mismatch. Sandbox credentials do not work against production endpoints, and vice versa. Make sure your base URL matches your credential environment.
• Incorrect API user/key. In the sandbox, you create an API user and API key programmatically. If these were not created correctly, authentication fails. Recreate them from scratch.

403 Forbidden

You are authenticated but not authorized for this operation. Causes:

• You are calling an API (e.g., Disbursements) that you have not subscribed to on the Developer Portal.
• Your production account has not been approved for the operation you are attempting.

400 Bad Request

Your request is malformed. Common causes:

• Missing required fields. The Request to Pay endpoint requires amount, currency, payer (with MSISDN), and external ID. Missing any of these returns a 400.
• Invalid phone number format. The MSISDN must be in the correct format for Rwanda. Try formats like 250780000000 (with country code, no plus sign) and verify against the API documentation.
• Invalid currency. Use "RWF" for Rwanda. Typos or wrong currency codes cause 400 errors.
• Duplicate external ID. Each transaction must have a unique reference. Reusing an external ID from a previous request may cause an error.

409 Conflict

A resource with the same ID already exists. Common when creating API users in the sandbox: if you reuse a reference ID, you get a 409. Generate a new UUID for each attempt.

422 Unprocessable Entity

The request is syntactically correct but semantically invalid. Check the response body for specific error details. Common cause: amount format issues (some APIs expect a string, others expect a number).

Callback problems are the most frustrating category because the error is silent: nothing happens. Your server does not receive the expected POST request, and you have no error message to debug.

"My callback is not being received"

Checklist:

1. Is your server publicly accessible? MoMo cannot reach localhost:3000. During development, use ngrok (ngrok http 3000) to get a public URL. Verify ngrok is running and your URL is current (ngrok URLs change on restart with the free tier).
2. Is your callback URL correct in the API request? The callback URL must be HTTPS. Check for typos. Include the full path (e.g., https://your-domain.com/api/momo/callback).
3. Is your server running and the route correct? Send a test POST to your callback URL manually (using curl or Postman) to verify your server responds.
4. Are there firewall issues? If your server is behind a firewall, MoMo's requests may be blocked. Ensure incoming POST requests from MoMo's IP ranges are allowed.
5. Is your server responding with 200 OK? If your callback handler crashes or returns an error, MoMo may not retry (or may retry on a schedule). Your handler should return 200 first, then process the callback asynchronously.

"I receive callbacks in sandbox but not in production"

Your production server must be deployed with HTTPS. The callback URL registered during production onboarding must match exactly. Verify your production server is accepting POST requests from external sources.

These errors come back in the callback or when you poll the transaction status.

FAILED: PAYER_NOT_FOUND (or similar)

The phone number does not have a MoMo account. Verify the number is correct and has an active MoMo wallet.

FAILED: NOT_ENOUGH_FUNDS

The customer does not have enough money in their MoMo wallet. Show a friendly message suggesting they top up and try again. Do not reveal the customer's balance.

FAILED: TRANSACTION_TIMED_OUT

The customer did not confirm the payment within the timeout period. They may not have seen the prompt, or they chose not to confirm. Allow them to retry.

FAILED: INTERNAL_PROCESSING_ERROR

An error on MoMo's side. This is not your fault. Implement retry logic with exponential backoff. If it persists, check MoMo's status page or contact their developer support.

PENDING (not transitioning to success or failure)

The transaction is stuck. This can happen if the USSD prompt was sent but the customer has not responded. Implement a timeout in your application (60 to 120 seconds) and show the customer a retry option. Also poll the status endpoint as a fallback.

When something is broken in your MoMo integration, follow this order:

1. Check the logs. Log every HTTP request you send (URL, headers, body) and every response you receive (status, body). The answer is almost always in the logs.
2. Isolate the failure point. Is the error in authentication? In the payment request? In the callback? Test each step independently using curl or Postman before looking at your application code.
3. Compare with the documentation. Open the MoMo API documentation and verify that your request matches the expected format exactly. Field names, data types, header names: all must match.
4. Check the sandbox vs production environment. Many production errors are caused by using the wrong environment. Verify your base URL, credentials, and callback URL all point to the same environment.
5. Test the callback independently. Send a manual POST request to your callback URL with a sample payload. If your server processes it correctly, the issue is on MoMo's side. If not, the issue is in your callback handler.

Detailed logging during development is the single most effective debugging tool. Every mobile money integration we have built at McTaba starts with comprehensive request and response logging. When something breaks (and it will), the logs tell you exactly where and why.

If you want structured, mentored support through this process, the McTaba mobile money integration course (approximately RWF 100,000) walks you through building a complete integration with error handling built in from the start. The debugging strategies you learn apply to MoMo, M-Pesa, Airtel Money, and any future mobile money API you encounter.