Documentation

HTTP Status codes translated to M-PESA API Error Codes

Project Mulla uses conventional 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 failed validation (e.g. a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with Project Mulla’s servers (these are seldom).

REFERENCE:

HTTP status code => MPESA G2 API SOAP status code => Description of the error


2xx - Successful

Successful

  • 200 => 00 => The Request has been successfully received or the transaction has successfully completed.

4xx - Client Error

Bad requests(incorrect/missing detials)

  • 400 => 09 => The store number specified in the transaction could not be found. This happens if the Merchant Pay bill number was incorrectly captured during registration.
  • 400 => 10 => This occurs when the system is unable to resolve the credit account i.e the MSISDN provided isn’t registered on M-PESA
  • 400 => 30 => Returned when the request is missing reference ID
  • 400 => 31 => Returned when the request amount is Invalid or blank
  • 400 => 36 => Response given if incorrect credentials are provided in the request (incorrent merchant info)
  • 400 => 40 => Missing parameters
  • 400 => 41 => MSISDN(phone no.) is in incorrect format
  • 400 => 42 => Your PASSKEY, PAYBILL_NUMBER or environment variables may be incorrect

Unauthorised

  • 401 => 32 => Returned when the account in the request hasn’t been activated. (unactivated)
  • 401 => 33 => Returned when the account hasn’t been approved to transact. (unapproved to transact)

Payment required, details are ok, but still fails

  • 402 => 01 => Insufficient Funds on MSISDN account
  • 402 => 03 => Amount less than the minimum single transfer allowed on the system.
  • 402 => 04 => Amount more than the maximum single transfer amount allowed.
  • 402 => 08 => Balance would rise above the allowed maximum amount. This happens if the MSISDN has reached its maximum transaction limit for the day.

Conflict found

  • 409 => 43 => Duplicate merchant transaction ID detected
  • 409 => 35 => Response when a duplicate request is detected.
  • 409 => 12 => Message returned when the transaction details are different from original captured request details.
  • 409 => 99 => There's no recorded transaction associated with the transaction ID provided

5xx - Server Error

Service Unavailable

  • 503 => 06 => Transaction could not be confirmed possibly due to confirm operation failure.
  • 503 => 11 => This message is returned when the system is unable to complete the transaction.
  • 503 => 34 => Returned when there is a request processing delay.
  • 503 => 29 => System Downtime message when the system is inaccessible.

Gateway Timeout

  • 504 => 05 => Transaction expired in the instance where it wasn’t picked in time for processing.