ERROR CODES

Error Codes Reference

Complete reference of all error codes returned by the API. Each error includes an HTTP status code, error code, and resolution steps.

HTTP Status Codes

Status	Description
200	Success — request processed successfully
400	Bad Request — invalid parameters or missing fields
401	Unauthorized — authentication failed
402	Payment Required — insufficient account balance
403	Forbidden — insufficient permissions
404	Not Found — resource doesn't exist
409	Conflict — duplicate reference or resource
429	Too Many Requests — rate limit exceeded
500	Internal Server Error — unexpected server error
503	Service Unavailable — provider is temporarily down

Error Response Format

All error responses follow a consistent JSON format:

{
  "success": false,
  "error": "Error message in human-readable format",
  "code": "ERROR_CODE",
  "details": {
    "field": "Specific field that caused the error",
    "reason": "Detailed explanation"
  }
}

Error Codes

INVALID_PHONE_NUMBER400

Phone number is not in E.164 format

Resolution: Ensure the phone number starts with '+' and includes country code (e.g., +265888123456)

MESSAGE_TOO_LONG400

Message exceeds maximum length for a single SMS

Resolution: Keep messages under 160 characters for standard SMS, or 70 characters for Unicode

MISSING_REQUIRED_FIELD400

A required field is missing from the request

Resolution: Check the API reference for required fields in the endpoint

INVALID_REFERENCE400

Reference ID format is invalid

Resolution: Use alphanumeric characters and underscores only

INVALID_TEMPLATE400

WhatsApp template name is invalid or not approved

Resolution: Verify template name and ensure it's approved in WhatsApp Business Manager

UNAUTHORIZED401

Missing or invalid authentication credentials

Resolution: Include a valid Bearer token in the Authorization header

TOKEN_EXPIRED401

The access token has expired

Resolution: Request a new token using /api/v1/auth/token

INVALID_CLIENT_CREDENTIALS401

client_id or client_secret is incorrect

Resolution: Verify your credentials and ensure they haven't been rotated

FORBIDDEN403

Your account doesn't have permission for this action

Resolution: Contact your administrator to grant the required permissions

RESOURCE_NOT_FOUND404

The requested resource doesn't exist

Resolution: Check the message_id or resource identifier

RATE_LIMIT_EXCEEDED429

Too many requests in the current time window

Resolution: Implement rate limiting in your app; retry after the Retry-After period

INSUFFICIENT_CREDITS402

Your account balance is too low to send this message

Resolution: Top up your account or contact your administrator

SMS_DELIVERY_FAILED200

Message was accepted but failed during carrier delivery

Resolution: Check delivery reports; the recipient may be unreachable or the number invalid

CARRIER_REJECTED200

The carrier rejected the message

Resolution: Verify the phone number is valid and the carrier supports this message type

PROVIDER_UNAVAILABLE503

The SMS/WhatsApp provider is temporarily unavailable

Resolution: Retry with exponential backoff; check system health at /api/monitoring/health

WEBHOOK_DELIVERY_FAILED200

Webhook could not be delivered to your URL

Resolution: Verify your webhook URL is accessible and returns HTTP 200

DUPLICATE_REFERENCE409

A message with this reference ID was already sent

Resolution: Use a unique reference ID for each request

OTP_EXPIRED200

The OTP code has expired

Resolution: Request a new OTP code using /api/v1/otp/send

OTP_MAX_ATTEMPTS200

Maximum verification attempts exceeded

Resolution: The user must request a new OTP code

INTERNAL_SERVER_ERROR500

An unexpected error occurred on the server

Resolution: Retry the request; contact support if the issue persists