Rate Limits and Fair Use

WUTS is tuned for high throughput across many tenants and does not enforce an aggressive per-tenant request cap on the gateway. In practice your traffic is bounded by two things: the gateway's HTTP timeouts, and the pacing WhatsApp itself applies to each connected device. This page explains both, and the fair-use practices that keep your number healthy.

How throughput actually works

Every send is bound to a connected device and is dispatched over that device's live WhatsApp session. The real ceiling is therefore the rate at which a single WhatsApp number can reasonably send — not an arbitrary number set by the gateway. Sending far faster than a human would, or blasting recipients who never opted in, is what gets a number flagged by WhatsApp, regardless of what the API allows.

Treat the gateway as a fast, fair pipe and shape your own traffic to look natural. The sections below give you the concrete knobs.

Gateway request timeouts

The HTTP server enforces connection-level timeouts to protect the service. These are the only hard, gateway-side limits you will hit under normal use:

Most calls complete in well under a second. The wide write timeout exists because some operations intentionally take longer — for example, a send with a long delay plus typingDuration (see below) holds the request open until the message is actually dispatched.

Built-in natural pacing

WUTS ships per-message pacing controls so you can make automated sends look human without writing your own scheduler. These are accepted by the send endpoints (POST /send/text, POST /send/audio, POST /send/template, and the other media sends):

curl -X POST https://api.wuts.com.br/send/text \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "text": "Hi! Thanks for reaching out.",
    "delay": 2,
    "typingDuration": 4
  }'

Using delay and typingDuration to spread out a batch — instead of firing hundreds of requests in the same instant — is the single most effective way to keep your number in good standing.

Recommended client-side practices

Because the gateway does not throttle you, you should pace yourself. The following patterns are what we recommend for any client sending at volume.

Limit concurrency

Cap the number of in-flight requests per device. A small concurrency window (for example, a handful of simultaneous sends per connected number) keeps the session responsive and avoids overwhelming a single WhatsApp account.

Spread out bulk sends

For campaigns or broadcasts, add a short gap between recipients rather than sending everything at once. Combine a client-side gap with the built-in delay to mimic human cadence. Sudden bursts to many new recipients are the classic trigger for WhatsApp spam flags.

Back off on 503 and 5xx

WUTS returns 503 Service Unavailable for transient conditions — for example, when a device is momentarily disconnected, still warming up (DEVICE_NOT_READY), or a downstream dependency is briefly unavailable. Treat 503 and any 5xx as retryable with exponential backoff and jitter:

# Pseudocode: retry with exponential backoff + jitter
attempt=0
max_attempts=5
while [ $attempt -lt $max_attempts ]; do
  status=$(curl -s -o /dev/null -w '%{http_code}' \
    -X POST https://api.wuts.com.br/send/text \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{"number":"5511999999999","text":"Hello"}')

  if [ "$status" = "200" ]; then break; fi
  # only retry transient failures
  case "$status" in 503|500|502|504) ;; *) break;; esac

  sleep_s=$(( (2 ** attempt) + (RANDOM % 2) ))   # 1s, 2s, 4s, ... + jitter
  sleep "$sleep_s"
  attempt=$((attempt + 1))
done

Do not retry 4xx responses blindly — a 400, 401, or 404 will not succeed on retry and indicates a problem with the request, token, or target. See Errors for the full status reference.

Honor delivery feedback

Watch your webhooks for delivery and read receipts. A rising rate of undelivered messages or blocks is an early signal that your sending pattern or audience needs adjustment — slow down before WhatsApp does it for you.

WhatsApp messaging policy and consent

WUTS connects real WhatsApp accounts, so WhatsApp's own messaging policies apply to everything you send. Responsible use is not optional — it protects your number from being banned.

Practical guidelines:

• Get consent first. Send only to people who agreed to be contacted on WhatsApp.
• Make opt-out easy. Respect requests to stop, and stop sending immediately.
• Keep it relevant. Personalized, expected, low-volume conversations are far safer than identical mass blasts.
• Warm up new numbers. A brand-new number sending at high volume on day one looks like spam. Ramp up gradually.
• Watch your quality signals. Blocks and reports degrade your number's standing; sustained natural pacing protects it.

Future commercial tiers

Related pages

• Quickstart — send your first message
• Conventions — request and response shapes, JID formats
• Errors — status codes and which ones are retryable
• Webhooks — react to delivery and read receipts