---
title: "SMS API Error Messages"
description: "Reference the standardized SMS API errors returned by Bulkit and understand how to handle them."
---

# 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:

```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"
}
```

### 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 is missing, inactive, or not assigned to your account.

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

### 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