Debugging Common STK Push Errors

Typical lifecycle

1. Server calls STK Push API — immediate response acknowledges request acceptance.
2. User receives PIN prompt on phone and either accepts or cancels.
3. Daraja calls your registered callbackUrl with final ResultCode.

Common issues & fixes

1. HTTP 4xx / 5xx from Daraja on STK request

1. Cause: malformed payload, invalid OAuth token, or missing required fields.
2. Fix: validate BusinessShortCode, Password format, Timestamp, and cached token validity.

2. Too many requests / rate limiting

1. Cause: sending many STK requests in rapid succession.
2. Fix: implement client-side throttling and exponential backoff on retries. Batch test calls in sandbox.

3. User cancels or PIN not entered

1. Symptom: callback ResultCode indicates user did not complete flow (non-zero).
2. Fix: treat this as an expected outcome — update order state to cancelled and present a retry option to the user.

4. No callback received

1. Cause: unreachable callbackUrl (network, DNS, SSL), or callback processing failures.
2. Fix: ensure publicly accessible HTTPS endpoint, check your server logs and implement a fallback transaction-status query to confirm.

Best practice: Always confirm finality

Do not mark transactions "paid" solely on STK request acceptance. Use the callback or transaction query endpoint to confirm ResultCode == 0 and that you have an MpesaReceiptNumber.