Resources

API Status & Error Handling

Complete reference for Statum API status codes and error responses (200, 401, 402, 422, 500). Learn robust error-handling strategies for production.

Building a resilient production integration requires handling exceptions and error states properly. Statum APIs utilize standard HTTP response status codes (RFC 2616) to indicate the success or failure of your API calls. Your application should inspect these status codes synchronously to decide whether to process the payload, alert operators, or initiate transaction retries.

HTTP Status Code Reference

Below is a comprehensive lookup table detailing the status codes returned by the Statum Gateway:

Status Code Meaning & Context Recommended Client Action
200 OK Request Successful No action required. Proceed with parsing the response body.
401 Unauthorized Authentication Failed Verify your base64-encoded Consumer Key & Secret pairing in the Authorization header. Do not retry automatically.
402 Payment Required Insufficient Funds Your wallet balance is insufficient. Top up your wallet using your dashboard M-Pesa code. Fail the transaction.
422 Unprocessable Entity Validation Error Inspect the description parameter. Verify request parameter layouts (e.g. phone number syntax).
429 Too Many Requests Rate Limit Exceeded Ease off request frequency. Implement throttling rules and queue retries with exponential backoff delays.
500 Server Error Gateway Error The gateway or operator network experienced an internal error. Safely queue the request for retry after a delay.

Implementing Error Handling in Production

A resilient backend integration should parse response codes and execute appropriate logic. We recommend separating client-side input errors from transient server errors:

  • Client Errors (400, 401, 422): These indicate code implementation or input problems. Do not retry these requests automatically; log them for developer review or prompt the user to correct their input.
  • Transient Errors (429, 500, 503): These represent temporary gateway or telco congestion. Queue these transactions internally and trigger automatic retries.

Integration Implementation Examples

Response Error Parsing 
<?php
$response = json_decode($result, true);

switch ($response['status_code']) {
    case 200:
        // Transaction initiated successfully. Map request_id.
        break;
    case 401:
        throw new Exception("Authentication Error: Validate Consumer Key/Secret.");
    case 402:
        throw new Exception("Insufficient Balance: Deposit funds into your wallet.");
    case 422:
        throw new Exception("Validation Failure: Check parameter format: " . $response['description']);
    case 429:
        // Wait and retry later (Throttling)
        retryWithBackoff($request);
        break;
    case 500:
    default:
        // Gateway or Carrier timeout. Schedule retry.
        retryWithBackoff($request);
        break;
}
?>
if (response.data.status_code !== 200) {
    console.error(`Statum API Error [${response.data.status_code}]: ${response.data.description}`);
    if (response.data.status_code === 402) {
        notifyFinanceTeam('Statum Wallet low balance warning!');
    }
    // Update local transaction logs
    db.transactions.update({ id: txnId }, { status: 'failed', error: response.data.description });
}

Resilient Retry Guidelines

When retrying failed requests (e.g. 500 Server Error), observe these best practices to avoid compounding server loads:

  • Exponential Backoff: Delay consecutive retry attempts exponentially (e.g. wait 2s, then 4s, 8s, 16s, etc.) rather than checking immediately.
  • Jitter: Add random micro-delays (jitter) to your retry calculations. This breaks up synchronized request batches from multiple client servers.