# Límites diarios de mensajes

Cada plan incluye un número de mensajes al día. El contador se reinicia a las **00:00 UTC**. Cuando llegas al límite, los nuevos mensajes se rechazan con `429 Too Many Requests` hasta el reinicio: no se almacenan y no se envía ninguna notificación push.

## Límites por plan

| Plan | Mensajes por día |
|------|-----------------:|
| Gratuito | 50 |
| Starter | 1.000 |
| Medium | 5.000 |
| Large | Ilimitado |

Tu plan actual y el uso de hoy están en la página de [Facturación](https://pocketalert.app/account/billing), y también puedes consultarlos por la API en [`GET /v1/messages/usage`](https://info.pocketalert.app/api/messages/usage.md).

## Qué cuenta

Cada mensaje creado en tu cuenta cuenta una vez, en el día UTC en que se creó:

- **Solicitudes a la API**: [`POST /v1/messages`](https://info.pocketalert.app/api/messages/create.md), incluidas las solicitudes con un adjunto.
- **Llamadas a webhooks**: cada llamada que genere un mensaje.
- **Mensajes programados**: se cuentan el día que los **programas**, no el día en que se envían. Un mensaje programado hoy para el próximo martes usa la cuota de hoy. El envío en sí nunca consume cuota ni se bloquea por ella.

Lo que no cuenta:

- Las solicitudes que fallan la validación (`400`, `403`) o fallan en nuestro lado (`500`): la cuota se devuelve.
- Las propias solicitudes rechazadas. Se registran aparte como `rejected` para que veas lo que te perdiste.

> **Warning: Borrar mensajes no libera cuota**
>
> El contador registra los mensajes enviados, no los almacenados. Borrar mensajes, uno a uno o todos a la vez, no devuelve la cuota de hoy.

## Cuando se alcanza el límite

La API responde `429 Too Many Requests` con un encabezado `Retry-After` que indica los segundos hasta el reinicio:

```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: Cómo gestionar el 429 en tu integración**
>
> Trata `429` como "ahora no", no como un fallo transitorio. Reintentar antes de que pase `Retry-After` devuelve la misma respuesta: cada reintento se rechaza y se cuenta. Espera hasta `resets_at` o descarta la alerta y regístrala en el log.

> **Warning: `curl --retry` puede quedarse esperando hasta medianoche**
>
> `curl --retry` trata `429` como reintentable y respeta `Retry-After`, así que un script que reintenta al superar el límite se duerme hasta las 00:00 UTC. Limita la espera con `--retry-max-time`:
>
> ```bash
> curl --retry 3 --retry-max-time 60 -X POST "https://api.pocketalert.app/v1/messages" ...
> ```

### Webhooks

Las llamadas a webhooks por encima del límite se rechazan con el mismo `429`, pero cada una queda registrada en el [historial](https://info.pocketalert.app/api/webhooks/history.md) del webhook, con su carga útil completa y el mensaje que habría generado. La entrada tiene `status: "error"` y `error_code: "daily_limit"`, así que nada desaparece sin dejar rastro. Abre el historial para ver qué llegó mientras estabas por encima del límite.

## Encabezados de límite de uso

Cada `POST /v1/messages` correcto (y cada llamada a un webhook que cree un mensaje) incluye la cuota actual:

| Encabezado | Significado |
|------------|-------------|
| `X-PA-Daily-Limit` | Mensajes permitidos al día en tu plan |
| `X-PA-Daily-Remaining` | Mensajes que quedan hoy, después de este |
| `X-PA-Daily-Reset` | Marca de tiempo Unix (segundos) del próximo reinicio, 00:00 UTC |

Los planes ilimitados no reciben estos encabezados.

## Correos electrónicos

Pocket Alert envía al titular de la cuenta como máximo dos correos al día:

- **Al 80%** del límite diario: un aviso mientras todavía hay margen.
- **Con el primer mensaje rechazado**: se ha alcanzado el límite y se están rechazando nuevos mensajes.

Los planes ilimitados nunca reciben estos correos.

## Cambiar de plan

Un plan nuevo se aplica de inmediato: una vez completada la mejora, la siguiente solicitud se comprueba con el nuevo límite, sin esperar al reinicio. Consulta los [precios](https://pocketalert.app/pricing).

## Relacionado

- [Crear mensaje](https://info.pocketalert.app/api/messages/create.md): la respuesta `429` en contexto
- [Uso de mensajes](https://info.pocketalert.app/api/messages/usage.md): el uso de hoy por la API
- [Historial de webhooks](https://info.pocketalert.app/api/webhooks/history.md): dónde se guardan las llamadas a webhooks rechazadas
- [Envío programado](https://info.pocketalert.app/features/scheduled-delivery.md): cómo se cuentan los mensajes programados
