> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Sending Limits

> GOWA does not rate-limit requests. What limits do exist, how WhatsApp restricts senders, and how to pace your traffic.

> [!WARNING]
>
> **GOWA has no rate limiter.** It does not count requests, return `429` for request volume, or send `X-RateLimit-*` headers. Every request you make is passed to WhatsApp immediately. Pacing is your responsibility.

## Limits GOWA does enforce

| Limit | Value | Result when exceeded |
| - | - | - |
| Request timeout | 45 s | `504 GATEWAY_TIMEOUT` |
| Request body | 100 MB | Request rejected (`413`) |
| Image / document / video upload | 20 / 50 / 100 MB | `400` validation error |
| Webhook delivery | 10 s per attempt, 5 attempts | Event dropped |

## Limits WhatsApp enforces

WhatsApp does not publish its limits for linked devices, and they change. Accounts that send too much, too fast, or to people who never wrote to them are restricted or banned. GOWA cannot detect or prevent this in advance.

The one signal GOWA surfaces is **`WA_REACHOUT_TIMELOCK`** (HTTP `429`):

```json theme={null}
{
  "code": "WA_REACHOUT_TIMELOCK",
  "message": "..."
}
```

WhatsApp returns this (server error 463) when the account is temporarily blocked from starting **new** chats. It cannot be bypassed or retried away. Until it lifts:

* Only message people who have messaged you first, or reply in existing chats.
* Sending one message from the phone itself sometimes clears it sooner.
* Stop bulk or cold outreach and slow down.

## Pacing guidelines

These are conservative starting points, not guarantees:

* Send sequentially per device; do not fire hundreds of concurrent requests.
* Add a delay between messages (several seconds, with random jitter) and longer pauses between batches.
* Prefer contacts who opted in or wrote first. Unsolicited messages get reported, and reports lead to bans.
* Warm up new numbers slowly over days.
* Personalize content; identical text to many recipients looks like spam.
* Stop on `WA_REACHOUT_TIMELOCK` and alert a human.

```python theme={null}
import random, time, requests

session = requests.Session()
session.auth = ("admin", "changeme")
session.headers["X-Device-Id"] = "my-device"

for phone, text in recipients:
    r = session.post("http://localhost:3000/send/message",
                     json={"phone": phone, "message": text}, timeout=60)
    body = r.json()
    if body.get("code") == "WA_REACHOUT_TIMELOCK":
        print("Reach-out blocked; stopping")
        break
    r.raise_for_status()
    time.sleep(random.uniform(5, 12))
```

For sends spread over time, use [scheduled sends](https://gowa-docs.mintlify.site/examples/scheduled-sends.md) instead of a long-running loop.

## Protecting GOWA itself

If GOWA is reachable from the internet, add request limits at your reverse proxy, especially for failed Basic Auth logins and, with MCP OAuth, `/oauth/authorize`. For example, with nginx:

```nginx theme={null}
limit_req_zone $binary_remote_addr zone=gowa:10m rate=10r/s;

server {
    location / {
        limit_req zone=gowa burst=20 nodelay;
        proxy_pass http://127.0.0.1:3000;
    }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.