Comprehensive error code reference for API integration troubleshooting and proper error handling.

Understand API error codes, M-Pesa result codes, and troubleshooting guidance for common issues.

API Error Codes

  1. Authentication Errors (HTTP 401)

    Authentication-related errors when API keys or tracking codes are invalid.

    MISSING_HEADERS
    Required headers (apikey, linkid) not provided

    INVALID_API_KEY
    API key not found or invalid

    INVALID_LINK_ID
    Shortcode tracking code not found or invalid

    INACTIVE_SHORTCODE
    Shortcode has been deactivated

  2. Validation Errors (HTTP 422)

    Request validation errors when parameters don't meet requirements.

    VALIDATION_ERROR
    Request parameters failed validation

    INVALID_MSISDN
    Phone number format invalid (must be 254XXXXXXXXX)

    INVALID_AMOUNT
    Amount must be between 1 and 300,000

    INVALID_CALLBACK
    Callback URL invalid or not accessible

  3. System Errors (HTTP 500)

    Internal system errors and M-Pesa integration failures.

    INTERNAL_ERROR
    Internal system error occurred

    STK_PUSH_FAILED
    M-Pesa STK Push initiation failed

    MPESA_UNAVAILABLE
    M-Pesa services temporarily unavailable

    TIMEOUT_ERROR
    Request timeout or processing delay
  4. M-Pesa Codes

M-Pesa Result Codes

  1. Success Codes

    Result codes indicating successful payment processing.

    0 - Success
    The service request is processed successfully.

  2. User Action Codes

    Result codes related to user actions and responses.

    1032 - User cancelled
    Request cancelled by user

    1037 - Timeout
    User did not respond to STK Push

    2001 - Invalid PIN
    Wrong PIN entered multiple times

  3. System & Balance Codes

    Result codes for system issues and balance-related problems.

    1 - Insufficient funds
    Customer has insufficient balance

    17 - Rule limited
    Transaction blocked by M-Pesa rules

    1025 - System error
    M-Pesa system error or USSD message too long

    9999 - System error
    General M-Pesa system error
  4. Troubleshooting

Troubleshooting Guide

  1. Authentication Issues

    Common authentication problems and solutions.

    Problem: INVALID_API_KEY
    Solution: Check API key from dashboard

    Problem: INVALID_LINK_ID
    Solution: Verify tracking code is correct

    Problem: MISSING_HEADERS
    Solution: Include both apikey and linkid headers

  2. Payment Failures

    Common payment failure scenarios and recommended actions.

    Insufficient Funds (Code 1):
    • Inform customer about balance
    • Suggest alternative payment methods

    User Cancelled (Code 1032):
    • Allow customer to retry
    • Provide clear cancellation message

    Timeout (Code 1037):
    • Implement retry mechanism
    • Set reasonable timeout expectations

  3. Webhook Issues

    Common webhook delivery problems and solutions.

    Webhook Not Received:
    • Check webhook URL is accessible
    • Ensure HTTPS for production
    • Verify endpoint returns HTTP 200

    Invalid Signature:
    • Check signature generation logic
    • Verify secret key is correct
    • Ensure raw payload is used for HMAC
  4. Best Practices