每日消息上限
每个套餐都包含每日的消息数量上限。计数会在 00:00 UTC 重置。达到上限后,新消息会被拒绝,返回 429 Too Many Requests,直到重置为止。这些消息不会被保存,也不会发送推送。
各套餐的上限
| 套餐 | 每日消息数 |
|---|---|
| 免费套餐 | 50 |
| Starter | 1,000 |
| Medium | 5,000 |
| Large | 无限制 |
你当前的套餐和今天的用量可以在账单页面查看,也可以通过 GET /v1/messages/usage 接口获取。
哪些会计入用量
你账户中创建的每条消息都计入一次,计入消息创建当天(UTC 时间)的用量:
- API 请求:
POST /v1/messages,包括带附件的请求。 - Webhook 调用:每次产生消息的调用。
- 定时消息:按你设定定时的那天计算,而不是按发送当天计算。今天设定的、下周二发送的消息会占用今天的配额。实际发送本身不消耗配额,也不会受配额限制。
以下情况不计入:
- 未通过校验的请求(
400、403)或服务端出错的请求(500)。这些请求的配额会被退还。 - 被拒绝的请求本身。它们会单独统计为
rejected,方便你查看错过了哪些消息。
删除消息不会释放配额
计数器统计的是已发送的消息数,而不是已保存的消息数。无论是逐条删除还是一次性全部删除,今天的配额都不会因此恢复。
达到上限时
API 会返回 429 Too Many Requests,并附带 Retry-After 响应头,其值为距离重置还需等待的秒数:
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{
"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"
}在你的集成中处理 429
请把 429 理解为“现在不行”,而不是临时故障。在 Retry-After 到期之前重试,得到的还是同样的结果,每次重试都会被拒绝并计入用量。你可以等到 resets_at 再发送,或者直接丢弃这条告警并记录日志。
curl --retry 可能会一直等到午夜
curl --retry 会把 429 视为可重试,并遵循 Retry-After,因此超限后,脚本会一直等到 00:00 UTC 才继续。请用 --retry-max-time 限制等待时间:
curl --retry 3 --retry-max-time 60 -X POST "https://api.pocketalert.app/v1/messages" ...Webhook
超出上限的 Webhook 调用同样会被拒绝,返回 429。但每次调用仍会记录在该 Webhook 的历史记录中,包括完整的负载以及它本应生成的消息。该条目的 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% 时:提醒你仍有剩余额度。
- 第一条消息被拒绝时:说明已达到上限,新消息正在被拒绝。
无限制套餐永远不会收到这些邮件。
升级套餐
新套餐会立即生效。升级完成后,下一个请求就会按新的上限进行检查,无需等待重置。详见价格。
相关内容
- 创建消息:结合上下文查看
429响应 - 消息用量:通过 API 查看今天的用量
- Webhook 历史记录:被拒绝的 Webhook 调用保存在这里
- 定时发送:了解定时消息如何计数