Bulkit
Register

SMS API Error Messages

Reference the standardized SMS API errors returned by Bulkit and understand how to handle them.

Last updated · Markdown version

Bulkit returns a fixed set of SMS API validation errors for common integration failures. These messages are designed to be stable, readable, and easy to map in application logic.

Endpoints

These errors apply to the documented SMS send endpoints, especially:

HTTP
POST /api/v2/messages/sms/bulk

Authorization

The error payload format is the same whether you authorize by JSON body, headers, or URL query parameters.

Error response

JSON
{
  "status": "error",
  "message": "Invalid sender ID"
}

Standard SMS API errors

Invalid credentials

Returned when the supplied API key and secret cannot be authenticated.

JSON
{
  "status": "error",
  "message": "Invalid credentials"
}

Insufficient balance

Returned when your account does not have enough credit to queue the requested SMS traffic.

JSON
{
  "status": "error",
  "message": "Insufficient balance"
}

You can top up your wallet cash balance or activate discounted Smart Bundles to acquire SMS credits instantly. Active bundle credits satisfy balance requirements even if your cash float balance is KSh 0.00.

Invalid number

Returned when one or more recipient phone numbers are not in a supported format.

JSON
{
  "status": "error",
  "message": "Invalid number"
}

Invalid sender ID

Returned when the sender ID or sender name is missing, invalid, inactive, or not authorized for your account.

JSON
{
  "status": "error",
  "message": "Invalid sender ID"
}

Strict Authorization & No Fallback: Bulkit strictly validates sender ownership and multi-client assignments across all API endpoints (v2 and legacy). If you specify a sender ID or sender name that does not exist, is inactive, or is not assigned to your account, the API immediately returns HTTP 400 Bad Request (Invalid sender ID). The system does not silently fall back or default to system senders (BULK_IT). If you intend to use the default system shortcode, you must explicitly supply "sender": "BULK_IT".

Invalid message

Returned when the SMS body is blank or otherwise fails validation.

JSON
{
  "status": "error",
  "message": "Invalid message"
}

Restricted send time

Returned when a promotional sender ID attempts to send to a Safaricom recipient outside the allowed send window.

JSON
{
  "status": "error",
  "message": "Restricted send time"
}

Safaricom promotional traffic rule

Safaricom promotional messages can only be sent between:

  • 8:00 AM
  • 6:00 PM

Timezone:

  • Africa/Nairobi

This rule applies to:

  • immediate sends made outside the allowed window
  • scheduled sends where scheduled_at falls outside the allowed window

Partial failures in bulk SMS

Bulk SMS can succeed for some recipients and fail for others. In that case, Bulkit returns a successful top-level response with a per-recipient failed array.

JSON
{
  "status": "success",
  "message": "Bulk SMS processed",
  "data": {
    "requested": 3,
    "queued": 2,
    "failed": [
      {
        "mobile": "12345",
        "message": "Invalid number"
      }
    ]
  }
}

Best practices

  • validate phone numbers before sending
  • verify available balance before high-volume requests
  • confirm sender IDs are assigned to the right account
  • use timezone-aware timestamps for scheduled sends
  • expect recipient-level failures in bulk workflows
PreviousHow to Get Delivery ReportsNextWhatsApp API Overview