# Limites

> Os limites da API do Messajo, do envio por número, da Meta e da retenção de dados.

## API do Messajo

Cada chave e cada organização têm um limite de requisições por minuto. Os dois valem ao mesmo tempo: a chamada passa só se couber nos dois.

| Escopo | Limite padrão |
|---|---|
| Por chave de API | 600 requisições/min (ajustável por chave até 6.000/min) |
| Por organização (todas as chaves somadas) | soma da vazão das conexões ativas × 60 × 1,25, no mínimo 1.200 requisições/min |

Os dois limites valem para os dois tipos de chave ([organização `mj_` e conexão `mjc_`](/api/authentication/#tipos-de-chave)). O limite por chave é de cada chave: cada chave de conexão tem o seu próprio contador de 600 requisições/min. O limite da organização é um só e soma o tráfego de todas as chaves, inclusive as de conexão, então várias chaves de conexão juntas ainda dividem a mesma vazão da organização.

Toda resposta da API `/v1` traz os cabeçalhos da janela atual:

| Cabeçalho | O que é |
|---|---|
| `X-RateLimit-Limit` | Limite da janela |
| `X-RateLimit-Remaining` | Quantas chamadas ainda cabem na janela |
| `X-RateLimit-Reset` | Quando a janela reinicia (Unix, em segundos) |

Passou do limite, a resposta é `429` com o código [`rate_limited`](/errors#rate_limited), o cabeçalho `Retry-After` (segundos) e o campo `retry_after_ms` no corpo. Espere esse tempo antes de repetir.

O limite da organização acompanha as conexões: dois números de 80 e 20 mensagens/s dão 7.500 requisições/min (100 × 60 × 1,25). Instagram e Messenger só entram na soma se tiverem vazão registrada. O valor é recalculado a cada 60 s, então conectar ou remover um número leva até 1 minuto para valer; `X-RateLimit-Limit` mostra o limite em vigor. Os demais valores podem mudar por plano.

## Envio por número

Cada número tem uma vazão máxima, que depende do modo da conexão. O Messajo lê a vazão junto com a saúde do número, a cada 15 minutos, e mostra em **Velocidade** na página da conexão:

| Modo | Vazão |
|---|---|
| Coexistência (app do celular + API) | 20 mensagens/s |
| Só API | 80 mensagens/s |
| Só API, com vazão alta liberada pela Meta | 1.000 mensagens/s (a Meta sobe sozinha) |

Cada número tem um balde de fichas com a capacidade da vazão (20, 80 ou 1.000) e que enche nesse ritmo por segundo. Cada chamada que vai para a Meta gasta uma ficha: o envio, pela camada simples ou pelo espelho, e o `typing`. Sem ficha, o Messajo responde `429` com o código [`connection_rate_limited`](/errors#connection_rate_limited), o cabeçalho `Retry-After` e o `retry_after_ms` no corpo, sem chamar a Meta. Nada é enfileirado: espere esse tempo e repita com a mesma `Idempotency-Key`.

Se a própria Meta recusar por vazão (`130429`, `80007` ou `4` em `meta_code`), a resposta é `429` [`meta_rate_limited`](/errors#meta_rate_limited). Como a Meta não processou o pedido, o Messajo repete sozinho quando a espera cabe em 2,5 s; acima disso, devolve o erro com o `retry_after_ms` que a Meta informar.

## Limite de mensagens da Meta

A Meta limita quantos **usuários únicos** o portfólio (Business Manager) alcança com mensagens iniciadas pela empresa em 24 horas móveis. O limite é **do portfólio** e é compartilhado entre todos os números dele.

Os degraus são 250 → 2.000 → 10.000 → 100.000 → ilimitado. Para subir:

- verificar a empresa no portfólio, ou
- manter boa qualidade e enviar para pelo menos metade do limite atual dentro de 7 dias.

A Meta reavalia o portfólio a cada 6 horas e sobe o degrau sozinha quando as condições são cumpridas. O Messajo lê o degrau atual (campo `whatsapp_business_manager_messaging_limit` do número) junto com a saúde e mostra em **Faixa de envio** na página da conexão; quando ele muda, sai `connection.updated` com `reason: "limit_changed"`. Respostas dentro de uma conversa aberta pelo contato não contam neste limite. As [campanhas](/guides/campaigns/#velocidade-e-a-faixa-do-portfólio) param sozinhas em 95 % da faixa e voltam quando ela libera.

Detalhes oficiais: [limites de mensagens da Meta](https://developers.facebook.com/docs/whatsapp/messaging-limits).

## Limite por par

A Meta também limita quantas mensagens um número manda para **o mesmo contato** em pouco tempo (da ordem de uma mensagem a cada 6 segundos, com pequenas rajadas). Acima disso, a resposta é `429` [`pair_rate_limited`](/errors#pair_rate_limited), com `131056` em `meta_code` e `retry_after_ms` de 6.000: espere e espace os envios para esse contato. O Messajo nunca repete esse erro sozinho.

## Janelas

| Canal | Regra |
|---|---|
| WhatsApp | Até 24 horas depois da última mensagem do contato, qualquer mensagem. Fora disso, só template aprovado. |
| Instagram e Messenger | Até 24 horas depois da última mensagem do contato; 7 dias depois de o contato responder a um anúncio. Com `tag: "human_agent"` (só resposta de pessoa), até 7 dias. Fora disso, `422` antes de chamar a Meta. |

No WhatsApp, o Messajo confere a janela antes de chamar a Meta: mensagem que não é template, fora da janela, volta `422` [`outside_service_window`](/errors#outside_service_window), com o fim da janela em `details[0].message`. Só a mensagem do contato abre a janela; o que você manda pelo app do celular na coexistência não abre.

## Instagram e Messenger

Cada conta do Instagram e cada Página do Messenger têm um balde de fichas, como os números do WhatsApp. Sem ficha, a resposta é `429` [`connection_rate_limited`](/errors#connection_rate_limited), sem chamar a Meta.

| Canal | Texto, reação, curtida, botões e cards | Mídia (imagem, `images`, áudio, vídeo, PDF) |
|---|---|---|
| Instagram | 100 mensagens/s | 10 mensagens/s (gasta também uma ficha de texto) |
| Messenger | 100 mensagens/s | 100 mensagens/s |

| Limite | Instagram | Messenger |
|---|---|---|
| Texto | 1.000 bytes | 2.000 caracteres |
| Imagens por mensagem | até 10 (`images`) | 1 |
| Anexo | imagem até 8 MB; áudio, vídeo e PDF até 25 MB | 25 MB |
| Publicações | 100 por conta em 24 h ([publicações](/connect/instagram-content/#limites)) | — |

Se a própria Meta recusar por vazão (`4`, `17`, `32`, `613` ou `80006`), a resposta é `429` [`meta_rate_limited`](/errors#meta_rate_limited) com o `retry_after_ms` que a Meta informar. Não há envio em massa nem campanhas no Instagram e no Messenger: a Meta não permite. Os números acima vêm da documentação da [Plataforma do Instagram](https://developers.facebook.com/docs/instagram-platform) e da [Plataforma do Messenger](https://developers.facebook.com/docs/messenger-platform) e ainda são conferidos em conta real.

## Ligações, grupos, Flows e pedidos

| Limite | Valor |
|---|---|
| Pedido de permissão de chamada (Meta) | 1 a cada 24 h e 2 a cada 7 dias para o mesmo contato ([Ligações](/guides/calls/)) |
| SDP de uma ligação | 64 KiB |
| Participantes por grupo | 8 ([Grupos](/guides/groups/)) |
| JSON de um Flow | 10 MiB; `PUT /v1/flows/{id}/json` até 30 por minuto por organização |
| Trocas no endpoint de um Flow | 1.200 por minuto por Flow; o seu handler tem 7 s e até 256 KiB de resposta ([Flows](/guides/flows/)) |
| Itens por pedido | 100 ([Vendas](/guides/commerce/)) |
| Upload de mídia (`POST /v1/media`) | 120 por minuto por organização |

## Tamanho do corpo

| Rota | Máximo |
|---|---|
| `/v1` (JSON) | 1 MiB |
| `POST /v1/media` | 100 MiB |
| `POST /v1/campaigns/{id}/recipients` | 20 MiB |
| `PUT /v1/flows/{id}/json` | 10 MiB |
| Painel (`/rpc`) | 2 MiB |

Acima disso, a resposta é `413` [`body_too_large`](/errors#body_too_large), sem processar nada.

## Retenção

| Dado | Prazo |
|---|---|
| Evento bruto recebido da Meta | 7 dias |
| Eventos e registro das entregas | 30 dias (ou o prazo da organização, se for menor) |
| Logs do painel (requisições da API) | 30 dias (ou o prazo da organização, se for menor) |
| Mensagens, mídias, conversas e contatos | 90 dias por padrão; o dono escolhe de 7 até o teto da instância |

Depois do prazo, o dado é apagado no expurgo diário. Detalhes em [Dados e privacidade](/operate/data-privacy/).

## Idempotency-Key

Mande o cabeçalho `Idempotency-Key` (um valor único por operação, por exemplo um UUID) nas chamadas que criam algo, como o envio de mensagem. A chave vale por **24 horas**: repetir a mesma chave nesse prazo devolve a resposta original, sem executar de novo. É assim que se repete um envio com segurança depois de um timeout.
