Resources

API Status Codes & Error Handling — Statum Reference

Master Statum API status codes (200, 401, 500). Learn to troubleshoot errors and handle responses for M-Pesa, Airtime, and SMS integrations.

Mastering API status codes is essential for building resilient applications. Statum APIs leverage standard HTTP response codes (RFC 2616) to communicate the outcome of every transaction. This guide provides a detailed breakdown of success, client-side errors, and server-side issues to help you troubleshoot and optimize your integration.

HTTP Status Code Reference

Understanding these codes helps you debug integrations faster. We recommend logging the status_code from every API response for audit trails.

Status Code Meaning & Context Recommended Action
200 OK Request Successful Proceed with processing the response payload.
401 Authentication Failed Verify your Base64 encoded credentials in the header.
402 Insufficient Funds Top up your wallet balance on the developer dashboard.
422 Validation Error Check required fields (e.g., phone number format).
429 Too Many Requests Ease off your request rate and implement backoff.
500 Server Error Possible gateway issue. Retry after 5-10 seconds.

How to Handle Errors in Production

Your application should gracefully handle non-200 responses. We recommend implementing a robust error parsing strategy to ensure your users receive clear feedback when transactions fail.

Example Error Handler 
<?php
                    $response = json_decode($result, true);

                    switch($response['status_code']) {
                    case 200:
                    // Success logic
                    break;
                    case 401:
                    throw new Exception("Authentication Error: Check your API keys.");
                    case 402:
                    throw new Exception("Payment Error: Insufficient wallet balance.");
                    case 422:
                    throw new Exception("Validation Error: " . $response['description']);
                    default:
                    throw new Exception("Gateway Error: " . $response['description']);
                    }
                    ?>
if (response.data.status_code !== 200) {
                    console.error(`API Error: ${response.data.description}`);
                    // Trigger UI notification
                    showToast('error', response.data.description);
                    }