# 每日消息上限

每个套餐都包含每日的消息数量上限。计数会在 **00:00 UTC** 重置。达到上限后，新消息会被拒绝，返回 `429 Too Many Requests`，直到重置为止。这些消息不会被保存，也不会发送推送。

## 各套餐的上限

| 套餐 | 每日消息数 |
|------|-----------------:|
| 免费套餐 | 50 |
| Starter | 1,000 |
| Medium | 5,000 |
| Large | 无限制 |

你当前的套餐和今天的用量可以在[账单](https://pocketalert.app/account/billing)页面查看，也可以通过 [`GET /v1/messages/usage`](https://info.pocketalert.app/api/messages/usage.md) 接口获取。

## 哪些会计入用量

你账户中创建的每条消息都计入一次，计入消息创建当天（UTC 时间）的用量：

- **API 请求**：[`POST /v1/messages`](https://info.pocketalert.app/api/messages/create.md)，包括带附件的请求。
- **Webhook 调用**：每次产生消息的调用。
- **定时消息**：按你**设定定时**的那天计算，而不是按发送当天计算。今天设定的、下周二发送的消息会占用今天的配额。实际发送本身不消耗配额，也不会受配额限制。

以下情况不计入：

- 未通过校验的请求（`400`、`403`）或服务端出错的请求（`500`）。这些请求的配额会被退还。
- 被拒绝的请求本身。它们会单独统计为 `rejected`，方便你查看错过了哪些消息。

> **Warning: 删除消息不会释放配额**
>
> 计数器统计的是已发送的消息数，而不是已保存的消息数。无论是逐条删除还是一次性全部删除，今天的配额都不会因此恢复。

## 达到上限时

API 会返回 `429 Too Many Requests`，并附带 `Retry-After` 响应头，其值为距离重置还需等待的秒数：

```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: 在你的集成中处理 429**
>
> 请把 `429` 理解为“现在不行”，而不是临时故障。在 `Retry-After` 到期之前重试，得到的还是同样的结果，每次重试都会被拒绝并计入用量。你可以等到 `resets_at` 再发送，或者直接丢弃这条告警并记录日志。

> **Warning: `curl --retry` 可能会一直等到午夜**
>
> `curl --retry` 会把 `429` 视为可重试，并遵循 `Retry-After`，因此超限后，脚本会一直等到 00:00 UTC 才继续。请用 `--retry-max-time` 限制等待时间：
>
> ```bash
> curl --retry 3 --retry-max-time 60 -X POST "https://api.pocketalert.app/v1/messages" ...
> ```

### Webhook

超出上限的 Webhook 调用同样会被拒绝，返回 `429`。但每次调用仍会记录在该 Webhook 的[历史记录](https://info.pocketalert.app/api/webhooks/history.md)中，包括完整的负载以及它本应生成的消息。该条目的 `status: "error"`，`error_code: "daily_limit"`，因此不会有任何内容无声丢失。打开历史记录即可查看超限期间收到的内容。

## 限流响应头

每个成功的 `POST /v1/messages` 请求（以及每个创建消息的 Webhook 调用）都会返回当前的配额信息：

| 响应头 | 含义 |
|--------|---------|
| `X-PA-Daily-Limit` | 你的套餐每日允许的消息数 |
| `X-PA-Daily-Remaining` | 本条消息发送后，今天剩余的消息数 |
| `X-PA-Daily-Reset` | 下一次重置时间（00:00 UTC）的 Unix 时间戳（秒） |

无限制套餐不会返回这些响应头。

## 邮件提醒

Pocket Alert 每天最多向账户所有者发送两封邮件：

- **用量达到每日上限的 80% 时**：提醒你仍有剩余额度。
- **第一条消息被拒绝时**：说明已达到上限，新消息正在被拒绝。

无限制套餐永远不会收到这些邮件。

## 升级套餐

新套餐会立即生效。升级完成后，下一个请求就会按新的上限进行检查，无需等待重置。详见[价格](https://pocketalert.app/pricing)。

## 相关内容

- [创建消息](https://info.pocketalert.app/api/messages/create.md)：结合上下文查看 `429` 响应
- [消息用量](https://info.pocketalert.app/api/messages/usage.md)：通过 API 查看今天的用量
- [Webhook 历史记录](https://info.pocketalert.app/api/webhooks/history.md)：被拒绝的 Webhook 调用保存在这里
- [定时发送](https://info.pocketalert.app/features/scheduled-delivery.md)：了解定时消息如何计数
