Error Codes

This page lists all API error codes returned by Galatext APIs. Errors are returned with a JSON body containing an error object with code and message fields.

Error Response Format

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of the error.",
    "statusCode": 422
  }
}

HTTP Status Codes

Status	Meaning
200 OK	Request succeeded
202 Accepted	Request accepted for processing
400 Bad Request	Malformed request syntax
401 Unauthorized	Missing or invalid authentication
402 Payment Required	Insufficient credits
403 Forbidden	Authenticated but not permitted
404 Not Found	Resource not found
409 Conflict	Resource conflict (e.g., duplicate)
413 Payload Too Large	Request exceeds size limits
422 Unprocessable Entity	Validation error
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Server-side error
503 Service Unavailable	Temporary service outage

Error Codes Reference

Authentication Errors

Status	Error Code	Description	Solution
401	MISSING_API_KEY	No API key provided in request	Add x-api-key header to your request
401	INVALID_API_KEY	The provided API key is not valid	Check your API key in the dashboard
401	EXPIRED_API_KEY	API key has been revoked or expired	Generate a new API key
401	INVALID_TOKEN	JWT token is invalid or malformed	Re-authenticate to get a new token
401	EXPIRED_TOKEN	JWT token has expired	Refresh your token

Validation Errors

Status	Error Code	Description	Solution
422	VALIDATION_ERROR	General validation failure	Check the errors array for details
422	INVALID_PHONE_NUMBER	Phone number not in valid E.164 format	Use format +254712345678 (country code + number)
422	MESSAGE_TOO_LONG	Message exceeds 1600 characters	Shorten your message
422	EMPTY_MESSAGE	Message body is empty	Provide message content
422	INVALID_SENDER_ID	Sender ID is not valid or not approved	Use a valid/sender ID or request approval
422	EMPTY_RECIPIENTS	Recipients array is empty	Provide at least one recipient
422	TOO_MANY_RECIPIENTS	Too many recipients for your tier	Reduce batch size or upgrade your plan
422	INVALID_MEDIA_URL	Media URL is invalid or inaccessible	Provide a valid, publicly accessible HTTPS URL
422	UNSUPPORTED_MEDIA_TYPE	Media format not supported	Check supported formats documentation

Account & Billing Errors

Status	Error Code	Description	Solution
402	INSUFFICIENT_CREDITS	Account balance too low	Top up credits from the dashboard
402	ACCOUNT_SUSPENDED	Account has been suspended	Contact support
403	ACCOUNT_NOT_VERIFIED	Account email not verified	Verify your email address
403	ACCOUNT_RESTRICTED	Account has temporary restrictions	Check dashboard for details

WhatsApp Errors

Status	Error Code	Description	Solution
403	WHATSAPP_OPT_IN_REQUIRED	Recipient has not opted in	Collect opt-in before sending
403	WHATSAPP_NUMBER_NOT_REGISTERED	Sender number not registered	Register a phone number in the dashboard
403	WHATSAPP_TEMPLATE_NOT_APPROVED	Template not yet approved	Wait for approval or check rejection reason
422	WHATSAPP_TEMPLATE_INVALID	Template parameters don't match	Check template variable count and order
422	WHATSAPP_MEDIA_TOO_LARGE	Media exceeds size limit	Compress or resize your media

Rate Limit Errors

Status	Error Code	Description	Solution
429	RATE_LIMIT_EXCEEDED	Too many requests per second	Implement backoff and retry logic
429	DAILY_QUOTA_EXCEEDED	Exceeded daily message quota	Upgrade your plan or wait for reset

Server Errors

Status	Error Code	Description	Solution
500	INTERNAL_ERROR	Unexpected server error	Retry after a few seconds
503	SERVICE_UNAVAILABLE	Service temporarily unavailable	Check status.galatext.com

Webhook Errors

Status	Error Code	Description	Solution
400	INVALID_WEBHOOK_URL	Webhook URL is not valid	Provide a valid HTTPS URL
400	WEBHOOK_VERIFICATION_FAILED	Webhook endpoint not responding	Ensure your endpoint returns 200 OK
400	DUPLICATE_WEBHOOK	Webhook URL already registered	Use a different URL or update existing

Handling Errors

JavaScript

async function sendSMS() {
  try {
    const response = await fetch('https://api.galatext.com/api/sms/send', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': process.env.GALATEXT_API_KEY
      },
      body: JSON.stringify({
        phoneNumber: '+254712345678',
        message: 'Hello!'
      })
    });

    const data = await response.json();

    if (!data.success) {
      switch (data.error.code) {
        case 'INSUFFICIENT_CREDITS':
          console.error('Please top up your account');
          break;
        case 'RATE_LIMIT_EXCEEDED':
          // Implement exponential backoff
          await new Promise(r => setTimeout(r, 1000));
          return sendSMS();
        default:
          console.error(`Error ${data.error.code}: ${data.error.message}`);
      }
      return;
    }

    console.log('Success:', data.data);
  } catch (error) {
    console.error('Network error:', error);
  }
}

Python

import time
import requests

def send_sms_with_retry():
    for attempt in range(3):
        response = requests.post(
            'https://api.galatext.com/api/sms/send',
            headers={
                'Content-Type': 'application/json',
                'x-api-key': 'YOUR_API_KEY'
            },
            json={
                'phoneNumber': '+254712345678',
                'message': 'Hello!'
            }
        )

        data = response.json()

        if data.get('success'):
            return data['data']

        error_code = data.get('error', {}).get('code')

        if error_code == 'RATE_LIMIT_EXCEEDED':
            wait = 2 ** attempt  # Exponential backoff
            time.sleep(wait)
            continue

        raise Exception(f"{error_code}: {data['error']['message']}")

    raise Exception("Max retries exceeded")

Best Practices

• Always check success — Don't assume requests succeed
• Use exponential backoff — For 429 and 5xx errors
• Handle all error codes — Gracefully degrade functionality
• Log error details — Capture error codes for debugging
• Monitor error rates — Sudden increases may indicate configuration issues