CallMePing
Log inStart Free Trial

API rate limits and error codes explained

To protect your number from WhatsApp bans, sending is limited per WhatsApp number, and every key has a limit on calls per minute. Errors always come back as JSON with an error message.

Rate limits

  • All calls: 120 per minute per API key.
  • Sending messages: 20 per minute and 1,000 per day per WhatsApp number, however many keys you use.
  • Group member changes (adding or removing members, and leaving a group): 20 per hour per WhatsApp number.
  • Enterprise plans get 5 times these limits.
  • Webhook calls to your server are not rate limited.

WhatsApp bans numbers, not keys. Creating more keys does not raise the sending limits.

When you hit a limit

The API returns HTTP 429 with a message that names the limit and says how many seconds to wait, for example: Rate limit exceeded: at most 20 messages per minute per WhatsApp number. Retry in 12s.

  1. Read the number of seconds after Retry in.
  2. Wait that long before sending again.
  3. Spread large sends out over time, or use scheduled posts, which spread sends over a few minutes for you.

Error format

Every error is JSON with an error message and an HTTP status.

Example error
HTTP/1.1 403
{"error": "This number hasn't messaged you yet, so it can't be replied to. Use scheduled posts or wait for them to write first."}

What each status means

  • 400: bad input. For example a missing text, a phone number without the country code, or media without a mimetype.
  • 401: missing, wrong or revoked API key.
  • 402: no active plan. The message is: The developer API needs an active plan.
  • 403: not allowed. For example messaging a number that has not written to you first.
  • 404: not found. For example a wrong group id or chat id.
  • 409: the AI is replying in that chat. Turn the AI off for the chat with POST /chats/{chatId}/ai before sending.
  • 429: rate limited. Wait the number of seconds in the message.
Was this article helpful?

Common questions

Can I get higher limits?

Enterprise plans get 5 times the standard API rate limits. Talk to us from the Enterprise card on Plan and billing.

Why do I get 402 when my key is correct?

Your account has no active plan, for example the trial ended or a payment failed and access ended. The account owner can choose a plan on Plan and billing.

Do scheduled posts count toward the API sending limit?

The API sending limit applies to messages sent through API calls. Scheduled posts have their own daily and per post limits.

Related articles