Plans and quotas
Four different ceilings apply to an integration, and they fail in four different ways. Confusing them is why a message that is refused looks unexplainable — so this page separates them, then gives the real numbers for each.
Four kinds of limit
Each has its own failure, its own remedy and its own place to look.
| Kind of limit | Code | Description |
|---|---|---|
| Plan entitlement | ENTITLEMENT_LIMIT_REACHED | How much of a resource your plan allows: contacts, channels, webhook endpoints. Fixed by the plan; raised by changing plan. |
| HTTP rate limit | RATE_LIMITED | How often you may call one route. Per workspace or per IP, over a short window. Wait and retry. |
| Provider throughput | PROVIDER_RATE_LIMITED | How fast the upstream provider will accept messages on a channel. Not something you can raise. |
| QR safety policy | QR_SAFETY_LIMIT_REACHED | A conservative cap the platform applies to unofficial QR channels. A policy choice, not a WhatsApp rule. |
Plan entitlements
GET/v1/planRead your own entitlements rather than hard-coding them — a workspace can carry an override, and the endpoint reports the effective value with its source.
| Entitlement | free | starter | growth | enterprise | Enforced |
|---|---|---|---|---|---|
| monthly_message_quota | Unlimited | Unlimited | Unlimited | Unlimited | Yes |
| production_channels | 1 | 3 | 10 | Unlimited | Yes |
| contacts | 500 | 10,000 | 100,000 | Unlimited | Yes |
| webhook_endpoints | 1 | 5 | 20 | Unlimited | Yes |
| shared_test_sessions | 1 | 1 | 1 | Unlimited | Yes |
| sandbox_message_quota | Unlimited | Unlimited | Unlimited | Unlimited | Not yet |
| verified_sandbox_recipients | 1 | 1 | 1 | Unlimited | Not yet |
| api_keys | 2 | 10 | 25 | Unlimited | Not yet |
| team_seats | 1 | 5 | 20 | Unlimited | Not yet |
| active_automations | 2 | 20 | 100 | Unlimited | Not yet |
| campaigns_enabled | false | true | true | true | Not yet |
| admin_log_retention_days | 7 | 30 | 90 | Unlimited | Not yet |
| support_tier | docs | standard | priority | sla | Not yet |
Not every entitlement is enforced yet
The keys marked as not enforced are reported by the plan endpoint but nothing counts against them today. Treat them as a published intention rather than as a limit you will hit — and do not build a billing assumption on one.
Current consumption comes from a separate endpoint, which reports the metered totals alongside the limits and what is left.
GET/v1/usage- The period is always the current
UTC calendar month, with an exclusive end. It is not a rolling thirty days and it is not the workspace's timezone. - The counts under
currentare live gauges, not period sums. Contacts, connected channels, keys and seats are all point-in-time. - The endpoint takes no parameters. There is no daily granularity and no way to ask for a past month, so a per-day figure cannot be derived from it.
HTTP rate limits
Rate-limited routes and their buckets. A denial is a 429 with a Retry-After header — see errors and limits for the headers in full.
| Endpoint | Limit | Scope |
|---|---|---|
| POST /v1/messages | 600 / 1min | workspace |
| POST /v1/channels | 20 / 1min | workspace |
| POST /v1/sandbox/sessions | 10 / 1h | workspace |
| POST /v1/sandbox/sessions/{id}/verify | 20 / 10min | workspace |
| POST /v1/contacts | 600 / 1min | workspace |
| POST /v1/contacts/imports | 20 / 1min | workspace |
| POST /v1/templates/{id}/test-send | 60 / 1min | workspace |
| POST /v1/conversations/{id}/messages | 600 / 1min | workspace |
| POST /v1/channels/{id}/qr/start | 30 / 1min | workspace |
They are configuration, not contract
These are the deployed defaults. Rate limiting is on in production and off elsewhere, and the numbers can be tuned, so read the headers rather than encoding a ceiling in your client.
Provider throughput
Every channel publishes a max_throughput_mps in its capabilities, and the dispatcher paces messages to it.
| Provider | Throughput | Description |
|---|---|---|
| sandbox | 2 msg/s | Comfortable for testing, and shared with nobody: the pool number is yours for the session. |
| qr | 0.5 msg/s | Deliberately slow. An unofficial client that sends quickly is a client that gets noticed. |
| meta | — | Not applicable yet. Meta tiers throughput by quality rating and messaging limit tier. |
Exceeding throughput does not fail a send. Messages queue and are dispatched in priority order, which is what the message category controls.
The QR safety limit
A platform policy, not a WhatsApp guarantee
A QR channel may send 200 outbound messages per rolling 24-hour window. Exceeding it is refused with QR_SAFETY_LIMIT_REACHED.
This number was chosen to be conservative. Staying under it does not make an account safe: WhatsApp's policies restrict unauthorised clients regardless of volume, and an account linked this way can be restricted at any time. Migrate to an official channel before volume matters.
- The window is
rolling, counted over the outbound messages actually sent, not a calendar day that resets at midnight. - It can be lowered per workspace or per channel, never raised without an explicit platform decision.
- A separate limit caps messages to any one recipient at
6per minute. - Marketing traffic is dispatched at the lowest priority, so it is the first thing a saturated channel delays.
Payload limits
| Limit | Value |
|---|---|
| Text message body (characters) | 4 096 |
| Template body (characters) | 1 024 |
| Contact import file (decoded) | 5 MiB |
| Contact import rows | 50 000 |
| List page size | 100 |
| Idempotency-Key (characters) | 255 |
Prices
The limits above are real and published. Prices are not decided yet, and the pricing page says so rather than showing a number nobody has agreed.