Resources

API Status & Error Handling

Reference for Statum API status codes and error responses, including 200, 401, 402, 422, 429, and 500, with practical handling and retry guidance.

Use the HTTP status code and the response body together when deciding what to do with a request. A successful response can be handled immediately; authentication and validation errors need a code or payload correction; temporary gateway errors may be retried only when the operation is safe to repeat.

HTTP Status Code Reference

The table below lists the response codes used in the current Statum documentation and the action normally associated with each one:

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

Handle validation and authentication failures differently from temporary service failures. Parse the JSON response, record the request_id where one is returned, and choose a retry policy that matches the operation:

  • Client-side failures (400, 401, 422): Check the request shape, credentials, and input values. Correct the cause before sending the request again.
  • Temporary failures (429, 500, 503): Record the failure, apply a bounded backoff, and retry only if repeating the operation cannot create a duplicate transaction.

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

If the API contract allows a failed request to be repeated, use a bounded retry policy. The aim is to give a temporary failure time to clear without sending a burst of identical requests:

  • Exponential backoff: Increase the delay between attempts instead of retrying immediately.
  • Jitter: Add a small random delay so several workers do not retry at exactly the same time.