feat: harden auth and stream uploads

docs/api.md

@@ -38,7 +38,7 @@ X-API-Key: <your-api-key>
 ### 2.3 匿名试用（仅网站场景）
 - 不提供 API Key；
 - 通过 Cookie 维持匿名会话（服务端签发），仅允许较小文件与较低频率。
-- 每日 10 次（以成功压缩文件数计）；超出返回 `QUOTA_EXCEEDED`（HTTP `402`）。
+- 每日 10 次；进入处理即预留次数，处理失败会自动归还，不可压缩或无体积收益的有效图片仍计次。超出返回 `QUOTA_EXCEEDED`（HTTP `402`）。
 - 日界：自然日（UTC+8），次日 00:00 重置。
 - **匿名试用硬限制：Cookie + IP 双限制**（两者任一超出都拒绝），降低刷会话绕过风险。
 
@@ -59,12 +59,9 @@ Idempotency-Key: <uuid-or-random-string>
 ### 3.2 限流（Rate Limit）
 超出限制返回：
 - HTTP `429`
-- 头：`Retry-After: <seconds>`
+- 错误码：`RATE_LIMITED`
 
-建议头（可选）：
-- `RateLimit-Limit`
-- `RateLimit-Remaining`
-- `RateLimit-Reset`
+API Key 按其 `rate_limit` 字段执行每分钟限制；登录、注册、找回密码和 Token 验证按 IP/账号执行独立限制。
 
 ### 3.3 配额（Quota / Billing）
 配额不足（当期额度耗尽）返回：
@@ -496,6 +493,8 @@ Content-Type: application/json
 { "name": "Production Server", "permissions": ["compress", "batch_compress"] }
 ```
 
+省略 `permissions` 时默认授予 `compress`；该权限覆盖同步压缩，并兼容批量任务、任务查询和结果下载。仅授予 `batch_compress` 时不能调用同步压缩接口。
+
 响应：
 ```json
 {
@@ -721,6 +720,8 @@ Content-Type: application/json
 }
 ```
 
+错误响应同时返回 `X-Request-Id`，其值与响应体 `request_id` 一致，可用于日志定位。
+
 ```http
 PUT /admin/storage/endpoints/{endpoint_id}
 POST /admin/storage/endpoints/{endpoint_id}/test