Rate limits
Rate limits keep one busy client from slowing the API for everyone, and they cap the damage a leaked key can do. Limits count requests in fixed 60-second windows.
The limits
Section titled “The limits”| Limit | Requests per 60 s | Counted per |
|---|---|---|
| Per API key | Your plan’s rate: 60 on Free, 300 on Starter, 1,200 on Pro, 3,000 on Business | API key |
| Per signed-in user | 300 | User |
| Per IP address | 600, or your plan’s per-key rate if that is higher | Client IP |
| Per organization | 1,200, or your plan’s per-key rate if that is higher | All keys and users of the organization together |
| Bulk operations | 20 | API key or user, on top of the limits above |
A request must pass all of them. The bulk limit applies to the expensive endpoints:
POST /v1/contact-importsandPOST /v1/contact-imports/:id/startGET /v1/contacts/export.csvPOST /v1/campaigns/:id/estimateandPOST /v1/campaigns/:id/start
GET /health is not rate limited.
Sending speed is a separate limit from the request rate: each phone keeps a cooldown between messages to protect your SIMs, and campaigns have their own ratePerMinute. See Send messages.
Headers
Section titled “Headers”Every response carries the state of your per-credential limit:
RateLimit-Limit: 300RateLimit-Remaining: 287RateLimit-Reset: 41| Header | Meaning |
|---|---|
RateLimit-Limit |
Requests allowed in the window. |
RateLimit-Remaining |
Requests left in this window. |
RateLimit-Reset |
Seconds until the window resets. |
Retry-After |
On a 429 from the per-credential limit: seconds to wait. |
When you hit a limit
Section titled “When you hit a limit”The API answers 429 Too Many Requests with code: "rate_limited":
{ "type": "https://docs.smsfabric.com/errors/rate_limited", "title": "Too Many Requests", "status": 429, "detail": "Rate limit exceeded. Retry in 18s.", "code": "rate_limited", "requestId": "req_v8y1b4e7h0k3n6q9t2w5z8c1"}Wait Retry-After seconds (or RateLimit-Reset when there is no Retry-After) and retry. If neither header is present, back off exponentially from one second. A 429 never sends anything, so the retry is safe; keep the same Idempotency-Key anyway.
# -i shows the RateLimit-* headerscurl -i https://api.smsfabric.com/v1/messages?limit=1 \ -H "X-Api-Key: $SMSFABRIC_API_KEY"import { SMSFabric } from '@smsfabric/sdk';
// The SDK retries 429 responses on its own, waiting Retry-After (or RateLimit-Reset).// maxRetries sets how many times (default 2).const sf = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY, maxRetries: 4 });
for await (const message of sf.messages.listAll({ status: 'failed' })) { console.log(message.id, message.errorCode);}import osimport timeimport requests
def get(url: str, **params) -> dict: headers = {"X-Api-Key": os.environ["SMSFABRIC_API_KEY"]} for attempt in range(5): res = requests.get(url, headers=headers, params=params, timeout=30) if res.status_code != 429: res.raise_for_status() return res.json() wait = res.headers.get("Retry-After") or res.headers.get("RateLimit-Reset") or 2 ** attempt time.sleep(int(wait)) raise RuntimeError("still rate limited")
print(get("https://api.smsfabric.com/v1/messages", limit=1))<?phpfunction getWithBackoff(string $url): array { for ($attempt = 0; $attempt < 5; $attempt++) { $headers = []; $ch = curl_init($url); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('SMSFABRIC_API_KEY')], CURLOPT_RETURNTRANSFER => true, CURLOPT_HEADERFUNCTION => function ($ch, $line) use (&$headers) { $parts = explode(':', $line, 2); if (count($parts) === 2) { $headers[strtolower(trim($parts[0]))] = trim($parts[1]); } return strlen($line); }, ]); $body = curl_exec($ch); if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 429) { return json_decode($body, true); } sleep((int) ($headers['retry-after'] ?? $headers['ratelimit-reset'] ?? 2 ** $attempt)); } throw new RuntimeException('Still rate limited');}
print_r(getWithBackoff('https://api.smsfabric.com/v1/messages?limit=1'));Rate limits and plan quotas
Section titled “Rate limits and plan quotas”Two different 429 answers can come back from a send. Branch on code:
429 rate_limited |
429 quota_exceeded |
|
|---|---|---|
| What ran out | Requests in the current 60-second window. | The plan’s messages for the day or the month (plan limits). |
| How long it lasts | Seconds: see Retry-After. |
Until 00:00 UTC, or the 1st of next month: see params.resetsAt. |
| What to do | Wait and retry with the same Idempotency-Key. |
Stop sending, keep the messages in your queue and send them after resetsAt. Retrying sooner gets the same answer. |
| Node SDK | Retried for you. | Thrown at once, never retried. |
Neither sends anything. To see how much allowance is left before a large send, read usage.messagesToday and usage.messagesThisMonth from GET /v1/org/plan (Plans).
Verify limits
Section titled “Verify limits”Verify has its own per-number, per-country and per-organization limits, which answer 429 verify_resend_limited or 429 verify_velocity_exceeded with Retry-After in seconds. Those waits are minutes long: show them to the user rather than retrying in a loop. See Verify phone numbers.
Stay under the limits
Section titled “Stay under the limits”- Use webhooks instead of polling message status.
- Batch up to 100 recipients per send (your plan’s
recipientsPerRequest). - Use
limit=200when you page through lists, andlistAll()in the SDK. - Spread scheduled jobs over the minute instead of firing them all at
:00.
All limits are listed on Limits.