# Limits

> The limits of the Messajo API, of sending per number, of Meta and of data retention.

## Messajo API

Each key and each organization has a per-minute request limit. Both apply at once: a call goes through only if it fits in both.

| Scope | Default limit |
|---|---|
| Per API key | 600 requests/min (adjustable per key up to 6,000/min) |
| Per organization (all keys combined) | sum of active connections' throughput x 60 x 1.25, at least 1,200 requests/min |

Both limits apply to both key types ([organization `mj_` and connection `mjc_`](/en/api/authentication/#key-types)). The per-key limit belongs to each key: every connection key has its own counter of 600 requests/min. The organization limit is a single one and adds up the traffic of all keys, connection keys included, so several connection keys together still share the same organization throughput.

Every `/v1` API response carries the headers of the current window:

| Header | What it is |
|---|---|
| `X-RateLimit-Limit` | Window limit |
| `X-RateLimit-Remaining` | How many calls still fit in the window |
| `X-RateLimit-Reset` | When the window resets (Unix, in seconds) |

Over the limit, the response is `429` with the [`rate_limited`](/en/errors#rate_limited) code, the `Retry-After` header (seconds) and the `retry_after_ms` field in the body. Wait that long before retrying.

The organization limit follows its connections: two numbers at 80 and 20 messages/s give 7,500 requests/min (100 x 60 x 1.25). Instagram and Messenger only count if they have a recorded throughput. The value is recalculated every 60 s, so connecting or removing a number takes up to 1 minute to apply; `X-RateLimit-Limit` shows the limit in effect. The other values may change per plan.

## Sending per number

Each number has a maximum throughput, which depends on the connection mode. Messajo reads the throughput together with the number's health, every 15 minutes, and shows it as **Speed** on the connection page:

| Mode | Throughput |
|---|---|
| Coexistence (phone app + API) | 20 messages/s |
| API only | 80 messages/s |
| API only, with high throughput granted by Meta | 1,000 messages/s (Meta raises it automatically) |

Each number has a token bucket with the throughput as its capacity (20, 80 or 1,000), refilled at that rate per second. Every call that goes to Meta spends one token: the send, through the simple layer or the mirror, and `typing`. With no token left, Messajo answers `429` with the [`connection_rate_limited`](/en/errors#connection_rate_limited) code, the `Retry-After` header and `retry_after_ms` in the body, without calling Meta. Nothing is queued: wait that long and retry with the same `Idempotency-Key`.

If Meta itself rejects for throughput (`130429`, `80007` or `4` in `meta_code`), the response is `429` [`meta_rate_limited`](/en/errors#meta_rate_limited). Since Meta did not process the request, Messajo retries on its own when the wait fits in 2.5 s; beyond that, it returns the error with the `retry_after_ms` Meta gives.

## Meta messaging limit

Meta limits how many **unique users** the portfolio (Business Manager) reaches with business-initiated messages in a rolling 24 hours. The limit belongs **to the portfolio** and is shared by all its numbers.

The tiers are 250 → 2,000 → 10,000 → 100,000 → unlimited. To move up:

- verify the business in the portfolio, or
- keep good quality and message at least half of the current limit within 7 days.

Meta re-evaluates the portfolio every 6 hours and raises the tier on its own when the conditions are met. Messajo reads the current tier (the number's `whatsapp_business_manager_messaging_limit` field) together with health and shows it as **Messaging tier** on the connection page; when it changes, `connection.updated` goes out with `reason: "limit_changed"`. Replies inside a conversation opened by the contact do not count toward this limit. [Campaigns](/en/guides/campaigns/#speed-and-the-portfolio-tier) stop on their own at 95% of the tier and resume when it frees up.

Official details: [Meta messaging limits](https://developers.facebook.com/docs/whatsapp/messaging-limits).

## Pair rate limit

Meta also limits how many messages a number sends to **the same contact** in a short time (roughly one message every 6 seconds, with small bursts). Above that, the response is `429` [`pair_rate_limited`](/en/errors#pair_rate_limited), with `131056` in `meta_code` and a `retry_after_ms` of 6,000: wait and space out the sends to that contact. Messajo never retries this error on its own.

## Windows

| Channel | Rule |
|---|---|
| WhatsApp | Up to 24 hours after the contact's last message, any message. Outside it, only an approved template. |
| Instagram and Messenger | Up to 24 hours after the contact's last message; 7 days after the contact replies to an ad. With `tag: "human_agent"` (replies from a person only), up to 7 days. Outside it, `422` before calling Meta. |

On WhatsApp, Messajo checks the window before calling Meta: a non-template message outside the window comes back `422` [`outside_service_window`](/en/errors#outside_service_window), with the end of the window in `details[0].message`. Only the contact's message opens the window; what you send from the phone app in coexistence does not.

## Instagram and Messenger

Each Instagram account and each Messenger Page has a token bucket, like WhatsApp numbers. Without a token, the answer is `429` [`connection_rate_limited`](/en/errors#connection_rate_limited), without calling Meta.

| Channel | Text, reaction, like, buttons and cards | Media (image, `images`, audio, video, PDF) |
|---|---|---|
| Instagram | 100 messages/s | 10 messages/s (also spends a text token) |
| Messenger | 100 messages/s | 100 messages/s |

| Limit | Instagram | Messenger |
|---|---|---|
| Text | 1,000 bytes | 2,000 characters |
| Images per message | up to 10 (`images`) | 1 |
| Attachment | image up to 8 MB; audio, video and PDF up to 25 MB | 25 MB |
| Publications | 100 per account in 24 h ([publications](/en/connect/instagram-content/#limits)) | — |

If Meta itself rejects for throughput (`4`, `17`, `32`, `613` or `80006`), the answer is `429` [`meta_rate_limited`](/en/errors#meta_rate_limited) with the `retry_after_ms` Meta reports. There is no bulk sending and no campaigns on Instagram and Messenger: Meta does not allow it. The numbers above come from the [Instagram Platform](https://developers.facebook.com/docs/instagram-platform) and [Messenger Platform](https://developers.facebook.com/docs/messenger-platform) docs and are still being checked on a real account.

## Calls, groups, Flows and orders

| Limit | Value |
|---|---|
| Call permission request (Meta) | 1 per 24 h and 2 per 7 days for the same contact ([Calls](/en/guides/calls/)) |
| Call SDP | 64 KiB |
| Participants per group | 8 ([Groups](/en/guides/groups/)) |
| Flow JSON | 10 MiB; `PUT /v1/flows/{id}/json` up to 30 per minute per organization |
| Exchanges on a Flow endpoint | 1,200 per minute per Flow; your handler has 7 s and up to 256 KiB of response ([Flows](/en/guides/flows/)) |
| Items per order | 100 ([Selling](/en/guides/commerce/)) |
| Media upload (`POST /v1/media`) | 120 per minute per organization |

## Body size

| Route | Maximum |
|---|---|
| `/v1` (JSON) | 1 MiB |
| `POST /v1/media` | 100 MiB |
| `POST /v1/campaigns/{id}/recipients` | 20 MiB |
| `PUT /v1/flows/{id}/json` | 10 MiB |
| Panel (`/rpc`) | 2 MiB |

Above that, the response is `413` [`body_too_large`](/en/errors#body_too_large), with nothing processed.

## Retention

| Data | Period |
|---|---|
| Raw event received from Meta | 7 days |
| Events and delivery records | 30 days (or the organization's deadline, if shorter) |
| Panel logs (API requests) | 30 days (or the organization's deadline, if shorter) |
| Messages, media, conversations and contacts | 90 days by default; the owner chooses from 7 up to the instance ceiling |

After the period, the data is deleted in the daily purge. Details in [Data and privacy](/en/operate/data-privacy/).

## Idempotency-Key

Send the `Idempotency-Key` header (a unique value per operation, such as a UUID) on calls that create something, like sending a message. The key is valid for **24 hours**: repeating the same key within that period returns the original response without running it again. That is how you safely retry a send after a timeout.
