Rate limits
Limits keep the SIM pool healthy and stop OTP abuse. Every limit answers 429 rate_limited, with Retry-After whenever it is known.
Per-client rate
Each API client may make up to 20 requests per second by default, across all v1 endpoints. The limit is per client, so separate apps on separate clients don't slow each other down. If you need more, talk to us.
Sending speed
The request rate is how fast we accept messages. Physical sending is paced per SIM (at most 30 sends per 30 minutes per SIM, Android's own limit) and spread across the pool, so a burst is accepted at once and delivered as SIMs become free.
OTP limits
POST /sms/otp/send has extra limits that protect your users and your balance from SMS-pumping and brute force:
| Limit | Scope | Value |
|---|---|---|
| Resend cooldown | Your client + number + purpose | 1 code per 60 s |
| Per number | The phone number, across every SMSRay customer | 3 codes per 10 min |
| Per end user IP | Your client + the ip you pass | 10 codes per 10 min |
| Per calling IP | Your client + your server's IP | 60 requests per minute |
| Verify attempts | Each code | 5 wrong tries, then locked |
| Code lifetime | Each code | 5 minutes |
The per-IP limit applies only when you pass ip. Pass your end user's IP, not your server's.
The 429 response
Every limit answers the same way. Retry-After (in seconds) is set whenever the wait is known, including the OTP resend cooldown.
429 response
HTTP/1.1 429 Too Many Requests
Retry-After: 42
content-type: application/json
{ "error": "Please wait before requesting another code", "code": "rate_limited" }Retrying well
- Honour
Retry-Afterwhen present; otherwise back off exponentially with jitter. - For OTP, show the remaining cooldown in your UI instead of letting users hammer the resend button.
- Reuse the same
Idempotency-Keywhen retrying a send so a retry can never double-send. - Smooth large batches on your side to stay under your per-second rate.