diff --git a/src/content/config/auth.mdx b/src/content/config/auth.mdx
index f21d9bc..ea5699d 100644
--- a/src/content/config/auth.mdx
+++ b/src/content/config/auth.mdx
@@ -69,7 +69,23 @@ Client Secret 保存后读不回来，面板只显示「已设置」。授权只
 
 ## 登录不通时
 
-失败原因都在 hub 日志里：
+登录页会显示失败原因：
+
+| 登录页的提示 | 含义 |
+|---|---|
+| 没有设置允许登录的 GitHub 用户 | 用户名列表是空的，空 = 拒绝所有人 |
+| GitHub 用户 X 不在允许登录的名单里 | 这个用户名不在列表里 |
+| 在 GitHub 上取消了授权 | 在 GitHub 授权页上点了拒绝 |
+| GitHub 拒绝了这次登录，原因见 hub 日志 | GitHub 返回了其他错误，例如 OAuth App 被停用 |
+| 登录已过期，请从登录页重新开始 | 不是从登录页发起的，或者 state cookie 已过期（10 分钟） |
+| GitHub 没有发放令牌，检查 Client Secret 是否正确后重新登录 | Client ID 或 Client Secret 不对 |
+| hub 连不上 GitHub，检查它的网络后重新登录 | hub 访问不了 github.com 或 api.github.com |
+| GitHub 的回复无法识别，稍后重新登录 | GitHub 回了内容，但不是预期的格式，多半是临时故障 |
+| GitHub 没有返回用户信息（HTTP 状态码），重新登录再试 | 读取 GitHub 用户名时被拒，例如令牌失效或请求被限流 |
+| hub 内部出错，详细原因见 hub 日志 | hub 自己出了错，例如写数据库失败 |
+
+hub 日志里另外记着 GitHub 的原始回复和用户名列表。任何 GitHub 账号都能走完授权看到登录页的提示，所以这两样
+只写进日志：
 
 ```bash
 # 一键脚本
@@ -78,16 +94,5 @@ journalctl -u monitor-hub -f | grep sign-in
 docker logs -f monitor 2>&1 | grep sign-in
 ```
 
-| 日志里的话 | 含义 |
-|---|---|
-| `no allowed GitHub users configured` | 用户名列表是空的，空 = 拒绝所有人 |
-| `GitHub user X is not on the allowed list` | 这个用户名不在列表里 |
-| `GitHub returned access_denied` | 在 GitHub 授权页上点了拒绝 |
-| `state mismatch or missing` | 不是从登录页发起的，或者 state cookie 已过期（10 分钟） |
-| `The client_id and/or client_secret passed are incorrect` | Client ID 或 Client Secret 不对 |
-
-同样的原因也会显示在登录页上，只是不带用户名列表：任何 GitHub 账号都能走完授权看到这句提示，列表只写进
-日志。
-
 日志里一条都没有，就是回调路径填错了：请求没有进到 hub 的任何处理逻辑。未匹配的 `/api/` 路径返回 404
 而不是页面，所以这种错误会直接显示出来。
diff --git a/src/content/config/notify.mdx b/src/content/config/notify.mdx
index 476cc8f..2c9aa17 100644
--- a/src/content/config/notify.mdx
+++ b/src/content/config/notify.mdx
@@ -42,7 +42,7 @@ Webhook。两个都配上时两边都发。
 
 ## 配置
 
-在面板的**通知**页填好渠道并保存，再点**发送测试**（测试用的是已保存的配置），每个渠道的报错会原样显示。
+在面板的**通知**页填好渠道并保存，再点**发送测试**（测试用的是已保存的配置），每个渠道失败的原因会显示在面板上。
 企业微信、钉钉、飞书例外，见下文[常见服务的写法](#常见服务的写法)。
 
 然后在同一页的**离线通知**卡片里勾选要关注的节点，可以全选，也可以先按分组筛选再全选，点**保存**后生效；
@@ -220,16 +220,25 @@ Webhook URL 也算凭证：Discord、Slack、企业微信、钉钉、Bark 的地
 
 ## 收不到通知
 
-先点**发送测试**，各渠道的错误会直接显示在面板上（企业微信、钉钉、飞书除外，看群里有没有收到）。常见的：
+先点**发送测试**，各渠道失败的原因会直接显示在面板上（企业微信、钉钉、飞书除外，看群里有没有收到）。常见的：
 
-| 报错 | 原因 |
+| 面板上的提示 | 原因 |
 |---|---|
-| `telegram: 401 Unauthorized` | token 填错，或者机器人被删了 |
-| `telegram: 400 Bad Request` … `chat not found` | Chat ID 不对，或者你还没给机器人发过消息、机器人不在群里 |
-| `telegram: 403 Forbidden` … `bot was blocked by the user` | 你屏蔽了机器人 |
-| `webhook: 301 Moved Permanently …` | URL 会跳转，改成它跳去的地址，见上面 Webhook 一节 |
-| `webhook: 4xx …` | 服务端拒收，后面跟着服务端自己的错误信息 |
-| `error sending request` | hub 连不上那个地址 |
+| `Telegram：Bot Token 不对（HTTP 401）` | token 填错，或者机器人被删了 |
+| `Telegram：Chat ID 不对，或者 bot 还没有加入这个会话（HTTP 400）` | Chat ID 不对，或者你还没给机器人发过消息、机器人不在群里 |
+| `Telegram：bot 被这个会话移除或屏蔽了（HTTP 403）` | 你屏蔽了机器人，或者机器人被移出了群 |
+| `Webhook：地址发生了跳转，请填写跳转后的地址（HTTP 301）` | URL 会跳转，改成它跳去的地址，见上面 Webhook 一节 |
+| `Webhook：对方拒收了这条消息，检查请求体格式（HTTP 400）` | 服务端拒收，多半是请求体不合它的格式 |
+| `连不上对方服务器`、`请求超时` | hub 连不上那个地址 |
+
+对方服务自己返回的错误信息写在 hub 日志里：
+
+```bash
+# 一键脚本
+journalctl -u monitor-hub | grep 'not delivered'
+# Docker
+docker logs monitor 2>&1 | grep 'not delivered'
+```
 
 测试能收到、真实事件收不到：
 
diff --git a/src/content/dev/theme.mdx b/src/content/dev/theme.mdx
index e288675..32fb8ee 100644
--- a/src/content/dev/theme.mdx
+++ b/src/content/dev/theme.mdx
@@ -17,6 +17,16 @@
 
 发布时打成 `theme.tar.gz`，解开就是这个目录。
 
+发布前用 `gzip -t` 检查一遍，没有输出就是完整的：
+
+```bash
+# 检查压缩流是否写完整，打包脚本没收尾时这里会报错
+gzip -t theme.tar.gz
+```
+
+hub 在安装和一键更新时会校验 gzip 尾部的校验和，不完整的包会被拒绝，面板提示「主题包损坏或不完整」。
+hub 1.3.0 及更早的版本不做这项检查，所以以前装得上的包，升级 hub 后可能装不上。
+
 ### theme.json
 
 `name` 到 `url` 六个字段**都要写**，都是字符串，后四个可以是空字符串；`config` 可以不写：
@@ -42,6 +52,7 @@
 | 解压后总量 | 64 MiB |
 | 单个文件 | 8 MiB |
 | 文件和目录数 | 2000 |
+| tar 结尾之后的填充 | 1 MiB |
 
 只接受普通文件和目录，包里有符号链接等其他类型时拒绝安装。
 
@@ -324,6 +335,15 @@ body 是整个设置对象，会替换已保存的那份，规则和面板相同
 第二种最容易漏。默认主题在渲染入口再检查一次指标是否完整，缺失或格式不对时显示「不可用」，不让一个
 节点的坏数据导致整个页面白屏。
 
+## 接口出错时
+
+hub 的错误回复一律是一行中文纯文本（`Content-Type: text/plain`），可以原样显示给访客，例如公开页关闭时的
+「需要登录后查看」、历史查询过多时的「查询历史的请求太多，稍后再试」。hub 1.3.0 及更早的版本这里是英文。
+
+不是 `text/plain` 的错误回复来自 hub 前面的反代或 CDN，比如 nginx 的 502 页面、Cloudflare 的拦截页。它们的
+内容不要显示出来，按状态码给一句说明。请求没发出去（断网），或者返回 200 却不是 JSON（被代理换成了网页），
+也按同样的办法处理。默认主题 `src/lib/api.ts` 里的 `api()` 就是这么写的，可以直接照抄。
+
 ## 路由
 
 未知路径回落到主题自己的 `dist/index.html`，客户端路由因此可用。`/admin`、`/api`、`/install.sh`、