SMS API Error Messages

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:

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

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

Standard SMS API errors

Invalid credentials

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

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

Insufficient balance

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

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

Invalid number

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

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

Invalid sender ID

Returned when the sender ID is missing, inactive, or not assigned to your account.

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

Invalid message

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

{
  "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.

{
  "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.

{
  "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