Skip to content

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.

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-imports and POST /v1/contact-imports/:id/start
  • GET /v1/contacts/export.csv
  • POST /v1/campaigns/:id/estimate and POST /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.

Every response carries the state of your per-credential limit:

RateLimit-Limit: 300
RateLimit-Remaining: 287
RateLimit-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.

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.

Terminal window
# -i shows the RateLimit-* headers
curl -i https://api.smsfabric.com/v1/messages?limit=1 \
-H "X-Api-Key: $SMSFABRIC_API_KEY"

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

  • Use webhooks instead of polling message status.
  • Batch up to 100 recipients per send (your plan’s recipientsPerRequest).
  • Use limit=200 when you page through lists, and listAll() in the SDK.
  • Spread scheduled jobs over the minute instead of firing them all at :00.

All limits are listed on Limits.