Documentation
Getting Started
API Reference
SMS API Contacts API OTP API Voice API MMS API WhatsApp API Viber API
HTTP API
HTTP Endpoints HTTP SMS API

Error Codes Reference

Complete reference of error codes and how to handle them.

HTTP Status Codes

Code Message Description Solution
200 OK Request successful No action needed
400 Bad Request Invalid request parameters Check your request format and parameters
401 Unauthorized Invalid or missing API key Check your API key in the Authorization header
403 Forbidden You don't have permission Check your account permissions
404 Not Found Resource not found Check the resource ID or endpoint URL
429 Too Many Requests Rate limit exceeded Wait before making more requests
500 Internal Server Error Server error Try again later or contact support
503 Service Unavailable Server temporarily unavailable Try again later

SMS API Error Codes

Code Message Description Solution
1001 Invalid Phone Number Phone number format is invalid Use international format: +254712345678
1002 Message Too Long Message exceeds 160 characters Shorten your message or split into multiple SMS
1003 Insufficient Balance Account balance is too low Add credit to your account
1004 Invalid Sender ID Sender ID is not approved Use an approved sender ID or request approval
1005 Duplicate Message Message was already sent recently Wait a moment before resending
1006 Invalid Message Type Message type is not supported Use a supported message type (SMS, OTP, etc.)
1007 Network Error Network error occurred Try again later
1008 Invalid Schedule Time Schedule time is in the past Use a future timestamp

OTP API Error Codes

Code Message Description Solution
2001 Invalid OTP Length OTP length must be between 4 and 8 Set length between 4-8
2002 Invalid Expiry Time Expiry time must be between 60 and 3600 seconds Set expiry between 60-3600 seconds
2003 OTP Not Found OTP code not found Generate a new OTP
2004 OTP Expired OTP code has expired Generate a new OTP
2005 Invalid OTP Code OTP code is incorrect Enter the correct OTP code
2006 Max Attempts Exceeded Too many failed OTP attempts Generate a new OTP

Error Response Format

Example Error Response

{
  "status": "error",
  "error": {
    "code": 1001,
    "message": "Invalid Phone Number",
    "details": "Phone number must be in international format"
  }
}

Handling Errors

PHP Example

<?php
$response = curl_exec($ch);
$result = json_decode($response, true);

if (isset($result['error'])) {
    $code = $result['error']['code'];
    $message = $result['error']['message'];
    
    switch ($code) {
        case 401:
            echo "Authentication failed - check your API key";
            break;
        case 1001:
            echo "Invalid phone number format";
            break;
        case 1003:
            echo "Insufficient balance - add credit";
            break;
        case 429:
            echo "Rate limit exceeded - wait before retrying";
            break;
        default:
            echo "Error: $message";
    }
}
?>

Python Example

import requests

try:
    response = requests.post(url, json=data, headers=headers)
    response.raise_for_status()
    result = response.json()
except requests.exceptions.HTTPError as e:
    error = e.response.json()
    code = error['error']['code']
    message = error['error']['message']
    
    if code == 401:
        print("Authentication failed")
    elif code == 1001:
        print("Invalid phone number")
    elif code == 1003:
        print("Insufficient balance")
    else:
        print(f"Error: {message}")

Common Issues and Solutions

401 Unauthorized

  • Check that your API key is correct
  • Ensure the Authorization header is properly formatted: Authorization: Bearer YOUR_API_KEY
  • Make sure your API key hasn't been revoked

1001 Invalid Phone Number

  • Use international format: +254712345678
  • Don't include spaces or dashes
  • Ensure the phone number is valid

1003 Insufficient Balance

  • Add credit to your account
  • Check your account balance
  • Contact support if you need help

429 Rate Limited

  • Wait before making more requests
  • Implement exponential backoff
  • Consider upgrading your plan

Getting Help

If you encounter an error not listed here:

Next Steps