跳到正文

每日消息上限 ​

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

各套餐的上限 ​

套餐每日消息数
免费套餐50
Starter1,000
Medium5,000
Large无限制

你当前的套餐和今天的用量可以在账单页面查看,也可以通过 GET /v1/messages/usage 接口获取。

哪些会计入用量 ​

你账户中创建的每条消息都计入一次,计入消息创建当天(UTC 时间)的用量:

  • API 请求:POST /v1/messages,包括带附件的请求。
  • Webhook 调用:每次产生消息的调用。
  • 定时消息:按你设定定时的那天计算,而不是按发送当天计算。今天设定的、下周二发送的消息会占用今天的配额。实际发送本身不消耗配额,也不会受配额限制。

以下情况不计入:

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

删除消息不会释放配额

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

达到上限时 ​

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"
}

在你的集成中处理 429

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

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 的历史记录中,包括完整的负载以及它本应生成的消息。该条目的 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% 时:提醒你仍有剩余额度。
  • 第一条消息被拒绝时:说明已达到上限,新消息正在被拒绝。

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

升级套餐 ​

新套餐会立即生效。升级完成后,下一个请求就会按新的上限进行检查,无需等待重置。详见价格。

相关内容 ​

Pocket Alert 文档