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

# WhatsApp Message Capping: What It Is and How to Handle It

> WhatsApp message capping limits how many new contacts you can message in a cycle. Learn the status levels, what happens when you hit the cap, and how Hypersender keeps you informed.

WhatsApp message capping is a quota that Meta places on how many new contacts a number can message in a cycle. When an account reaches the cap, WhatsApp blocks messages to new contacts until the cycle resets. Messages to existing conversations keep working.

This guide covers what message capping is, how to read the status levels, what happens when you hit the cap, and how Hypersender shows your quota so you can plan around it.

## What is WhatsApp message capping?

Meta limits the number of new contacts an account can message in a cycle. A new contact is a number with no existing chat history. The cycle has a start and an end, and the quota resets on its own when the cycle ends.

Message capping is a volume limit. It is not a block on your account. Your instance stays connected and working while the cap is active.

<Warning>
  Hypersender cannot remove or reset a message cap. Only Meta controls when the quota resets. Do not restart or re-pair your instance to try to clear it. The cap clears on its own.
</Warning>

## Status levels

Meta reports the cap as one of four statuses. Each status shows how close you are to the limit.

| Status           | Meaning                                                                             |
| ---------------- | ----------------------------------------------------------------------------------- |
| `NONE`           | No cap is active on this account.                                                   |
| `FIRST_WARNING`  | You are approaching the quota. Slow down outreach to new contacts.                  |
| `SECOND_WARNING` | You are close to the quota. Slow down before you hit the cap.                       |
| `CAPPED`         | You reached the quota. Messages to new contacts are blocked until the cycle resets. |

The status moves through these levels as you use the quota:

```mermaid actions={false} theme={null}
flowchart LR
    A[NONE] --> B[FIRST_WARNING]
    B --> C[SECOND_WARNING]
    C --> D[CAPPED]
    D -->|Cycle resets| A
```

Each status also carries two numbers:

| Field        | Meaning                                                                                       |
| ------------ | --------------------------------------------------------------------------------------------- |
| `totalQuota` | New-chat messages allowed in the current cycle. A value of `-1` means the account has no cap. |
| `usedQuota`  | New-chat messages already used in the current cycle.                                          |

The cycle start and end are Unix timestamps. The end time is the clock for when the quota resets.

## What happens when you are capped

When the status is `CAPPED`, messages to new contacts fail until the cycle ends.

* Messages to new contacts fail with an error.
* Messages to existing conversations keep working.
* Incoming messages keep working.
* Your instance stays connected. You do not need to scan a QR code.

<Info>
  The quota counts one-to-one messages to contacts without an established chat. It does not count replies to existing conversations.
</Info>

## How Hypersender shows your quota

Hypersender reads the capping status from your instance and shows it in three places.

### Dashboard progress bar

When a cap is active, your connection page shows a progress bar with the used and total quota.

The bar shows:

* The percentage of the quota you have used.
* The used and total numbers, for example "640 of 1,000 messages".
* The time left until the quota resets.

The bar color changes as you approach the cap:

| Status           | Bar color |
| ---------------- | --------- |
| `FIRST_WARNING`  | Amber     |
| `SECOND_WARNING` | Orange    |
| `CAPPED`         | Red       |

### Email notification

You receive an email when the status changes. The email shows the used and total quota, the percentage, and the reset time. You receive one email per status level per cycle, so we do not spam you.

### API error message

When your app tries to message a new contact while the account is capped, the API returns HTTP 423 with a clear message. The message includes the time left when the quota resets:

```
Meta has capped this instance's new-chat messages for the current cycle. Hypersender cannot override this. The quota resets in 12 days, 4 hours. You can send to numbers with an existing conversation, or use a different instance.
```

## What to do when you hit the cap

1. **Keep messaging existing contacts.** These conversations still work.
2. **Use another number for new contacts.** If you need to reach new contacts now, switch to a different instance.
3. **Let the quota reset.** The cap lifts on its own at the cycle end. Trying to bypass it does not help.
4. **Review your volume.** If you hit the cap often, spread outreach across more numbers.

## Message capping vs timelock

Message capping and a timelock are two different restrictions. Both block messages to new contacts, but they work in different ways.

|                | Message capping                  | Timelock                              |
| -------------- | -------------------------------- | ------------------------------------- |
| What it limits | Number of new contacts per cycle | New-contact outreach for a set period |
| Trigger        | Reaching the new-contact quota   | Messaging too many new contacts       |
| Send error     | `server returned error 475`      | `server returned error 463`           |
| Resets         | At the cycle end                 | At the restriction end                |
| Session        | Stays connected                  | Stays connected                       |

Read [Understanding WhatsApp Timelock Restrictions](/v2/hypersender/overview/whatsapp/whatsapp-timelock-restrictions) for details on the other restriction.

## Prevent the cap

The cap tracks new-contact messages. The best way to stay under it is to keep outreach within healthy limits.

* Warm up new numbers before sending at scale. See [Warming Up New Phone Numbers for WhatsApp API](/v2/hypersender/overview/whatsapp/warm-up-your-whatsapp-number).
* Let customers message you first when possible.
* Add more numbers and spread outreach across them.

Read the full [guide on avoiding blocks](/v2/hypersender/overview/whatsapp/avoid-getting-blocked) for a complete checklist.

## Related

* [How we handle WhatsApp message capping](https://hypersender.com/en/blog/how-we-handle-whatsapp-message-capping) on the Hypersender blog.
* [Hypersender dashboard](https://app.hypersender.com) to check your instances.

<Card title="Read the Full Guide" icon="shield" href="/v2/hypersender/overview/whatsapp/avoid-getting-blocked">
  Complete guide on how to avoid getting blocked on WhatsApp.
</Card>