SMS GatewayDocumentation

Rate Limits

The SMS Gateway API enforces rate limits to ensure fair usage and platform stability. Understanding these limits helps you design resilient integrations.

Overview

Rate limits are applied per organization and measured on a rolling window basis. When you exceed a rate limit, the API returns a 429 Too Many Requests response. Limits can be customized through the Developer Portal.

Default Rate Limits

CategoryLimitScope
SMS Send
100 req/min
Per organization
Bulk SMS
10 req/min
Per organization
OTP Send
30 req/min
Per organization
OTP Verify
50 req/min
Per organization
Webhook Management
Standard
Per organization
API Key Management
Standard
Per organization
Analytics
Standard
Per organization
Contacts
Standard
Per organization

Rate Limit Headers

Every API response includes headers that indicate your current rate limit status:

response-headers
1HTTP/1.1 200 OK
2X-RateLimit-Limit: 100
3X-RateLimit-Remaining: 87
4X-RateLimit-Reset: 1705320060
5Content-Type: application/json
X-RateLimit-LimitMaximum number of requests allowed in the current window.
X-RateLimit-RemainingNumber of requests remaining in the current window.
X-RateLimit-ResetUnix timestamp (seconds) when the current rate limit window resets.

Handling 429 Responses

When you receive a 429 response, implement exponential backoff with the Retry-After header to determine when to retry:

rate-limit-handler.ts
1async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
2  for (let attempt = 0; attempt < maxRetries; attempt++) {
3    const response = await fetch(url, options);
4
5    if (response.status === 429) {
6      const retryAfter = parseInt(response.headers.get('Retry-After') || '1', 10);
7      const delay = retryAfter * 1000 * Math.pow(2, attempt);
8      await new Promise(resolve => setTimeout(resolve, delay));
9      continue;
10    }
11
12    return response;
13  }
14  throw new Error('Max retries exceeded');
15}

Exponential backoff formula:

delay = Retry-After × 1000 × 2^attempt

This ensures you wait progressively longer between retries while respecting the server's recommended wait time.

Custom Rate Limit Configuration

You can view and update your organization's rate limits through the Developer API.

GET
/api/v1/developer/rate-limitsGet current limits
PATCH
/api/v1/developer/rate-limitsUpdate limits
get-limits.sh
1curl -X GET https://api.smsgateway.com/api/v1/developer/rate-limits \
2  -H "Authorization: Bearer <jwt_token>"
limits-response.json
1{
2  "perMinute": 100,
3  "perHour": 3000,
4  "perDay": 30000,
5  "enabled": true,
6  "currentUsage": {
7    "perMinute": 13,
8    "perHour": 847,
9    "perDay": 12450
10  }
11}

Update Request Body

perMinute
optional
integer — Maximum requests per minute.
perHour
optional
integer — Maximum requests per hour.
perDay
optional
integer — Maximum requests per day.
enabled
optional
boolean — Enable or disable rate limiting entirely.
update-limits.sh
1curl -X PATCH https://api.smsgateway.com/api/v1/developer/rate-limits \
2  -H “Authorization: Bearer <jwt_token>“ \
3  -H "Content-Type: application/json" \
4  -d '{
5    "perMinute": 150,
6    "perHour": 5000,
7    "perDay": 50000,
8    "enabled": true
9  }'

Best Practices

Exponential Backoff

Always implement exponential backoff when receiving 429 responses. Never retry immediately.

Idempotency Keys

Use idempotency keys for SMS send requests to prevent duplicate messages from retries.

Monitor Headers

Proactively check X-RateLimit-Remaining to throttle requests before hitting limits.

Use Bulk Endpoints

For sending multiple messages, use the bulk SMS endpoint instead of many individual requests.

Related Pages

SDK Examples

Code examples with built-in retry logic.

Error Codes

HTTP 429 error response details.