Rate Limits

To ensure fair usage and platform stability, API requests are rate limited.

Default Limits

Resource	Limit	Window
Send SMS	100 requests	per minute
Schedule SMS	50 requests	per minute
Other endpoints	200 requests	per minute

Rate Limit Headers

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1711234567

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the limit resets

Exceeding the Limit

When you exceed the rate limit:

HTTP/1.1 429 Too Many Requests

{
  "success": false,
  "error": "Rate limit exceeded. Please wait 60 seconds.",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 60
}

The retry_after field indicates how many seconds to wait before retrying.

Best Practices

1. Implement Exponential Backoff

async function sendWithRetry(data, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
 
    if (response.status === 429) {
      const result = await response.json();
      const waitTime = result.retry_after || Math.pow(2, attempt) * 1000;
      await new Promise((resolve) => setTimeout(resolve, waitTime * 1000));
      continue;
    }
 
    return response;
  }
  throw new Error("Max retries exceeded");
}

2. Use Comma-Separated Phones

Instead of sending multiple requests for individual recipients, send a comma-separated phone value:

// ✓ Good: One request with comma-separated phones
{
  "senderId": "MyBrand",
  "phone": "233200000000,233201111111,233202222222",
  "message": "Hello!"
}
 
// ✗ Bad: Multiple requests for each recipient
// POST /api/send-sms { "phone": "233200000000", ... }
// POST /api/send-sms { "phone": "233201111111", ... }
// POST /api/send-sms { "phone": "233202222222", ... }

3. Monitor Rate Limit Headers

Check X-RateLimit-Remaining before making requests:

if (rateLimitRemaining < 10) {
  // Slow down or queue requests
}

Higher Limits

If you need higher rate limits for your use case, contact support with:

Your account ID
Current usage patterns
Requested limit increase
Business justification

Resource

Limit

Window

Send SMS

100 requests

per minute

Schedule SMS

50 requests

per minute

Other endpoints

200 requests

per minute

Rate Limit Headers

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1711234567

Header

Description

X-RateLimit-Limit

Maximum requests allowed in the window

X-RateLimit-Remaining

Requests remaining in current window

X-RateLimit-Reset

Unix timestamp when the limit resets

Best Practices

1. Implement Exponential Backoff

async function sendWithRetry(data, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
 
    if (response.status === 429) {
      const result = await response.json();
      const waitTime = result.retry_after || Math.pow(2, attempt) * 1000;
      await new Promise((resolve) => setTimeout(resolve, waitTime * 1000));
      continue;
    }
 
    return response;
  }
  throw new Error("Max retries exceeded");
}

2. Use Comma-Separated Phones

Instead of sending multiple requests for individual recipients, send a comma-separated phone value:

// ✓ Good: One request with comma-separated phones
{
  "senderId": "MyBrand",
  "phone": "233200000000,233201111111,233202222222",
  "message": "Hello!"
}
 
// ✗ Bad: Multiple requests for each recipient
// POST /api/send-sms { "phone": "233200000000", ... }
// POST /api/send-sms { "phone": "233201111111", ... }
// POST /api/send-sms { "phone": "233202222222", ... }

3. Monitor Rate Limit Headers

Check X-RateLimit-Remaining before making requests:

if (rateLimitRemaining < 10) {
  // Slow down or queue requests
}