# Limiti giornalieri di messaggi

Ogni piano include un numero di messaggi al giorno. Il conteggio si azzera alle **00:00 UTC**. Una volta raggiunto il limite, i nuovi messaggi vengono rifiutati con `429 Too Many Requests` fino al reset: non vengono salvati e non viene inviata alcuna notifica push.

## Limiti per piano

| Piano | Messaggi al giorno |
|------|-----------------:|
| Gratuito | 50 |
| Starter | 1.000 |
| Medium | 5.000 |
| Large | Illimitati |

Il piano attuale e l'utilizzo di oggi sono disponibili nella pagina [Fatturazione](https://pocketalert.app/account/billing) e tramite API su [`GET /v1/messages/usage`](https://info.pocketalert.app/api/messages/usage.md).

## Cosa conta

Ogni messaggio creato nel tuo account conta una volta, nel giorno UTC in cui è stato creato:

- **Richieste API**: [`POST /v1/messages`](https://info.pocketalert.app/api/messages/create.md), incluse le richieste con allegato.
- **Chiamate webhook**: ogni chiamata che genera un messaggio.
- **Messaggi programmati**: contano il giorno in cui li **programmi**, non il giorno in cui vengono consegnati. Un messaggio programmato oggi per il martedì successivo usa la quota di oggi; la consegna in sé non consuma quota e non viene mai bloccata da essa.

Cosa non conta:

- Le richieste che non superano la validazione (`400`, `403`) o che falliscono lato nostro (`500`): la quota viene rimborsata.
- Le richieste rifiutate. Vengono conteggiate a parte come `rejected`, così puoi vedere quali messaggi ti sei perso.

> **Warning: Eliminare i messaggi non libera quota**
>
> Il contatore tiene traccia dei messaggi inviati, non di quelli conservati. Eliminare messaggi, uno alla volta o tutti insieme, non restituisce la quota di oggi.

## Quando si raggiunge il limite

L'API risponde con `429 Too Many Requests` e con un header `Retry-After` che indica il numero di secondi mancanti al reset:

```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: Gestire il 429 nella tua integrazione**
>
> Tratta `429` come "non adesso", non come un errore temporaneo. Riprovare prima che scada `Retry-After` ottiene la stessa risposta: ogni tentativo viene rifiutato e conteggiato. Puoi aspettare fino a `resets_at`, oppure scartare l'avviso e registrarlo nei log.

> **Warning: `curl --retry` può restare bloccato fino a mezzanotte**
>
> `curl --retry` considera `429` un errore ritentabile e rispetta `Retry-After`, quindi uno script che riprova oltre il limite resta in attesa fino alle 00:00 UTC. Limita il tempo di attesa con `--retry-max-time`:
>
> ```bash
> curl --retry 3 --retry-max-time 60 -X POST "https://api.pocketalert.app/v1/messages" ...
> ```

### Webhook

Le chiamate webhook oltre il limite vengono rifiutate con lo stesso `429`, ma ognuna viene comunque registrata nella [cronologia](https://info.pocketalert.app/api/webhooks/history.md) del webhook, con il payload completo e il messaggio che avrebbe generato. La voce ha `status: "error"` e `error_code: "daily_limit"`, quindi nulla va perso: apri la cronologia per vedere cosa è arrivato mentre eri oltre il limite.

## Header dei limiti di frequenza

Ogni `POST /v1/messages` riuscito (e ogni chiamata webhook che crea un messaggio) include la quota attuale:

| Header | Significato |
|--------|---------|
| `X-PA-Daily-Limit` | Messaggi consentiti al giorno nel tuo piano |
| `X-PA-Daily-Remaining` | Messaggi rimasti per oggi, dopo questo |
| `X-PA-Daily-Reset` | Timestamp Unix (secondi) del prossimo reset, alle 00:00 UTC |

I piani illimitati non ricevono questi header.

## Email

Pocket Alert invia al proprietario dell'account al massimo due email al giorno:

- **All'80%** del limite giornaliero: un avviso mentre c'è ancora margine.
- **Al primo messaggio rifiutato**: il limite è stato raggiunto e i nuovi messaggi vengono respinti.

I piani illimitati non ricevono mai queste email.

## Upgrade

Un nuovo piano si applica subito: appena l'upgrade va a buon fine, la richiesta successiva viene verificata con il nuovo limite, senza bisogno di aspettare il reset. Vedi [prezzi](https://pocketalert.app/pricing).

## Correlati

- [Crea messaggio](https://info.pocketalert.app/api/messages/create.md): la risposta `429` nel contesto
- [Utilizzo messaggi](https://info.pocketalert.app/api/messages/usage.md): l'utilizzo di oggi tramite API
- [Cronologia webhook](https://info.pocketalert.app/api/webhooks/history.md): dove vengono conservate le chiamate webhook rifiutate
- [Invio programmato](https://info.pocketalert.app/features/scheduled-delivery.md): come vengono conteggiati i messaggi programmati
