# Limites diários de mensagens

Cada plano inclui uma quantidade de mensagens por dia. A contagem é zerada às **00:00 UTC**. Quando você atinge o limite, novas mensagens são rejeitadas com `429 Too Many Requests` até a zeragem — elas não são armazenadas e nenhuma notificação push é enviada.

## Limites por plano

| Plano | Mensagens por dia |
|-------|------------------:|
| Gratuito | 50 |
| Starter | 1.000 |
| Medium | 5.000 |
| Large | Ilimitado |

Seu plano atual e o uso de hoje estão na página [Cobrança](https://pocketalert.app/account/billing), e também podem ser consultados pela API em [`GET /v1/messages/usage`](https://info.pocketalert.app/api/messages/usage.md).

## O que conta

Toda mensagem criada na sua conta conta uma vez, no dia UTC em que foi criada:

- **Requisições de API** — [`POST /v1/messages`](https://info.pocketalert.app/api/messages/create.md), incluindo requisições com anexo.
- **Chamadas de webhook** — cada chamada que gera uma mensagem.
- **Mensagens agendadas** — contadas no dia em que você **agenda** a mensagem, não no dia em que ela é entregue. Uma mensagem agendada hoje para a próxima terça usa a cota de hoje. A entrega em si nunca consome cota e nunca é bloqueada por ela.

O que não conta:

- Requisições que falham na validação (`400`, `403`) ou que falham do nosso lado (`500`) — a cota é devolvida.
- As próprias requisições rejeitadas. Elas são contabilizadas separadamente como `rejected`, para você ver o que deixou de enviar.

> **Warning: Excluir mensagens não libera cota**
>
> O contador registra mensagens enviadas, não mensagens armazenadas. Excluir mensagens — uma a uma ou todas de uma vez — não devolve a cota de hoje.

## Quando o limite é atingido

A API responde com `429 Too Many Requests` e um cabeçalho `Retry-After` com o número de segundos até a zeragem:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 30142
X-PA-Daily-Limit: 50
X-PA-Daily-Remaining: 0
X-PA-Daily-Reset: 1790035200
```

```json
{
  "error": "Daily message limit reached (50/50). New messages are rejected until 00:00 UTC. Upgrade your plan to raise the limit.",
  "limit": 50,
  "used": 50,
  "resets_at": "2026-09-22T00:00:00Z",
  "upgrade_url": "https://pocketalert.app/pricing"
}
```

> **Tip: Tratando 429 na sua integração**
>
> Trate `429` como "agora não", e não como uma falha temporária. Tentar de novo antes de `Retry-After` expirar recebe a mesma resposta — cada nova tentativa é rejeitada e contabilizada. Espere até `resets_at` ou descarte o alerta e registre-o no log.

> **Warning: `curl --retry` pode travar até a meia-noite**
>
> `curl --retry` trata `429` como repetível e respeita `Retry-After`, então um script que tenta de novo acima do limite fica parado até 00:00 UTC. Limite o tempo de espera com `--retry-max-time`:
>
> ```bash
> curl --retry 3 --retry-max-time 60 -X POST "https://api.pocketalert.app/v1/messages" ...
> ```

### Webhooks

Chamadas de webhook acima do limite são recusadas com o mesmo `429`, mas cada uma continua registrada no [histórico](https://info.pocketalert.app/api/webhooks/history.md) do webhook, com o payload completo e a mensagem que teria sido gerada. A entrada tem `status: "error"` e `error_code: "daily_limit"`, então nada desaparece sem deixar rastro. Abra o histórico para ver o que chegou enquanto você estava acima do limite.

## Cabeçalhos de limite de taxa

Toda requisição `POST /v1/messages` bem-sucedida (e toda chamada de webhook que cria uma mensagem) traz a cota atual:

| Cabeçalho | Significado |
|-----------|-------------|
| `X-PA-Daily-Limit` | Mensagens permitidas por dia no seu plano |
| `X-PA-Daily-Remaining` | Mensagens restantes hoje, após esta |
| `X-PA-Daily-Reset` | Timestamp Unix (segundos) da próxima zeragem, às 00:00 UTC |

Planos ilimitados não recebem esses cabeçalhos.

## E-mails

A Pocket Alert envia no máximo dois e-mails por dia ao titular da conta:

- **Em 80%** do limite diário — um aviso enquanto ainda há espaço.
- **Na primeira mensagem rejeitada** — o limite foi atingido e novas mensagens estão sendo recusadas.

Planos ilimitados nunca recebem esses e-mails.

## Upgrade

Um novo plano passa a valer imediatamente: assim que o upgrade for concluído, a próxima requisição é verificada contra o novo limite, sem precisar esperar a zeragem. Veja [preços](https://pocketalert.app/pricing).

## Relacionados

- [Criar mensagem](https://info.pocketalert.app/api/messages/create.md) — a resposta `429` no contexto
- [Uso de mensagens](https://info.pocketalert.app/api/messages/usage.md) — uso de hoje pela API
- [Histórico de webhooks](https://info.pocketalert.app/api/webhooks/history.md) — onde ficam as chamadas de webhook rejeitadas
- [Envio agendado](https://info.pocketalert.app/features/scheduled-delivery.md) — como as mensagens agendadas são contadas
