API Status & Error Handling

Building a highly resilient production integration requires developers to implement robust exception handling and error parsing strategies within their codebase. Statum APIs utilize standard HTTP response status codes (compliant with RFC 2616 specification guidelines) to indicate the immediate success or failure of all incoming API requests. Your server-side application should inspect these status codes synchronously to determine whether to process the payload, alert operations teams, or schedule programmatic transaction retries.

HTTP Status Code Reference

Below is a comprehensive and structured lookup reference table detailing the HTTP response status codes returned by the Statum gateway along with recommendations for client-side actions:

Implementing Error Handling in Production

A highly resilient backend integration must programmatically parse the returned JSON response codes and execute the appropriate business logic. To optimize system stability, we strongly recommend separating client-side input validations and credential errors from transient, carrier-level server exceptions:

• Client-Side Failures (400, 401, 422): These status codes indicate structural validation issues, invalid request layouts, or incorrect authentication credentials within your codebase. Developers should never configure automatic retries for these codes; instead, log the errors for immediate engineering review or prompt the end-user directly to correct their parameters.
• Transient Gateway Exceptions (429, 500, 503): These response codes represent temporary system congestion, telecommunication carrier downtime, or rate-limiting thresholds. Your system should capture these exceptions, queue the transactions internally, and initiate automated retry routines to guarantee message delivery.

Integration Implementation Examples

<?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 implementing retry mechanisms for failed requests (such as a 500 Gateway Server Error), developers should adhere to these industry-standard guidelines to prevent compounding server loads and avoiding gateway denial-of-service states:

• Exponential Backoff: Delay consecutive retry attempts exponentially (for example, waiting 2 seconds before the first retry, 4 seconds before the second, 8 seconds, 16 seconds, and so forth) instead of continuously hitting the endpoint immediately.
• Jitter Introduction: Introduce randomized micro-delays (jitter) into your backoff calculation routines to break up synchronized request batches coming from multiple client microservices, protecting the gateway from request spikes.