Documentation

Rate limits & quotas

TextMeFlow enforces two independent layers: per-number rate limits (protecting your WhatsApp number from Meta bans) and per-plan monthly quotas (what you pay for). This page explains both, and what your code should do when it hits them.

1. Per-number rate limits

These exist to keep your number safe — WhatsApp blocks numbers that behave like spam cannons. They apply to every send path (native API, TextMeBot-compat endpoint, no-code integrations):

• 1 message per second sustained
• 60 messages per minute
• 1,000 messages per hour

Burst limits get softer once your number has been sending for a few weeks — a "warm" number with a healthy delivery history gets more headroom than a freshly linked one. Read anti-spam best practices for the full picture (risk score, opt-in, STOP handling, quiet hours).

2. What a 429 looks like

Above the rate limit, the API returns 429 Too Many Requests. Don't retry immediately in a tight loop — back off and retry with exponential delay. Queued sends are the better pattern: push messages to your own queue and drain it at ≤1 msg/sec.

3. Monthly quotas per plan

Separate from rate limits, every plan has a monthly message quota — Free is 50 messages/month (lifetime), paid plans start at €5/month. See pricing for current tiers. Two things happen as you approach the quota:

• At 80% usage we email you a warning
• At 100% new sends are rejected with 429 and error quota_exceeded — messages are never silently queued into the next period

HTTP/1.1 429 Too Many Requests
{"error": "quota_exceeded", "monthly_quota": 500, "used": 500}

Upgrading takes effect immediately (pro-rata); alternatively the counter resets at the start of the next billing period.

4. Patterns that keep you out of trouble

• Spread batches: 200 reminders at 08:00 sharp will trip the per-minute limit — schedule them across a window
• Handle 429 distinctly from 4xx validation errors: one is "later", the other is "never"
• Monitor the quota_exceeded payload fields (monthly_quota, used) to build your own usage alerts
• Vary message content — identical text to many recipients raises the internal risk score even below the rate limit