Error Reference

Understanding error codes and how to handle them in your integration.

Error Response Format

All API errors return a consistent JSON structure:

{
  "success": false,
  "error": {
    "code": "INVALID_PHONE",
    "message": "Invalid phone number format",
    "details": "Phone number must be in format 254XXXXXXXXX"
  }
}

Validation Errors

When multiple fields fail validation, the response includes an errors array:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "errors": [
      { "field": "phoneNumber", "message": "Required field" },
      { "field": "amount", "message": "Must be a positive number" },
      { "field": "orderId", "message": "Must be between 1-50 characters" }
    ]
  }
}

HTTP Status Codes

M-PESA Payment Errors

Card Payment Errors

Payout Errors

Rate Limiting

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1705312800

Error Handling Best Practices

if (!response.success) {
  console.error(response.error.code, response.error.message);
  // Handle error appropriately
}

async function retryRequest(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status === 429 || err.status >= 500) {
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      throw err;
    }
  }
}

console.error('Payment failed:', {
  code: error.code,
  message: error.message,
  requestId: response.headers['x-request-id'],
  timestamp: new Date().toISOString()
});