浏览文档 +

常见问题

遇到问题时,请记下请求时间、HTTP 状态码和 request_id。分享截图或日志前请隐藏你的 key。

请求成功了,但没有收到通知#

200 表示 Apple 或 Google 已接受通知,不代表手机已经显示。请按顺序检查:

  1. App 中的链接与脚本中的一致。重置链接会更换 key。
  2. 系统设置中允许 Breeze 发送通知。
  3. 专注模式或勿扰模式没有把它隐藏。可以试试 level=timeSensitive,或检查 Breeze 的专注模式过滤器。
  4. 分组没有在“设置 → 已静音的分组”中被静音。
  5. 在 Android 上,对应级别的 Breeze 通知渠道已开启,且电池优化没有限制 App。

如果通知出现在历史记录中却没有横幅,问题出在系统设置,而不是投递。

返回 404#

key 不存在或已失效。重置链接、重装 App 或只复制了部分链接时都会这样。请从 App 复制当前链接并更新脚本。

返回 422#

目标设备不支持某个参数。常见原因:critical(暂不可用),以及 Android 上的 badge、ciphertext、自定义铃声或 sound=none。响应中的 error 会指出问题。删除该参数,或查看 参数 中的平台一列。

返回 429#

短时间内请求过多。请等待 Retry-After 给出的秒数后再试。限制按 key 和公网 IP 计算,同一办公室或家庭网络下的设备共用额度。当前限制见 API 参考。

同一条通知收到了两次#

超时或连接中断可能发生在 Apple 或 Google 已接受通知之后,此时重试会再显示一次。超时后不要自动重试,收到 207 后也不要向整组重发。给消息设置 id,重试时就会替换第一条,而不是多出一条。

图片或声音没有加载#

图片、头像和远程铃声必须使用 HTTPS,并在 10 秒内下载完成。远程铃声必须是 .caf 文件,最大 6 MB。自定义铃声的名称必须与“设置 → 声音”中显示的一致。

在 App 中重置链接,旧 key 从下一次请求起失效。然后更新所有使用旧链接的脚本和工具。key 只能用来发送,别人无法用它读取你的历史记录。

能用原来的 Bark 脚本吗?#

大多数可以。把域名和 key 换成你的 Breeze 链接即可。路径写法、带 device_key 的 /push 以及 Bark 的参数名都能使用。

能自建服务器吗?#

不能。Breeze 只在 push.breezelabs.dev 提供托管服务,App 无需任何设置即可使用。如需对服务保密内容,请使用加密。

支持 Android 吗?#

支持。Android 使用相同的链接和大部分参数。加密、自定义铃声、角标和关键警报目前仅限 iPhone。

能用关键警报吗?#

暂时不能,需要 Apple 授予权限。在此之前,请用 level=timeSensitive 配合 call=1。见 声音与提醒级别。

服务正常吗?#

服务状态 页面会检查服务本身及其与 Apple、Google 的连接。