# 错误与排障

开放 API 的错误格式始终以 HTTP 状态和 `error.code` 为准。请记录 `request_id`、接口模板和状态码；不要记录 Authorization、完整邀请链接或远程信息。

| HTTP | code | 原因与处理 |
| --- | --- | --- |
| 400 | `HTTPS_REQUIRED` | 使用正确 HTTPS 地址；不要先把密钥发给 HTTP 再等待跳转 |
| 400 | `INVALID_JSON` | JSON 缺失、格式错误或不是对象 |
| 400 | `CREDENTIALS_IN_URL` | 移除 URL 凭证，使用 Authorization；已经进入日志的密钥应撤销 |
| 400 | `BODY_NOT_ALLOWED` | 撤销邀请不要发送正文 |
| 400 | `IDEMPOTENCY_KEY_REQUIRED` | 创建邀请缺少合法请求编号 |
| 401 | `INVALID_API_KEY` | 密钥缺失、错误、到期或被撤销；检查个人中心，停止盲目重试 |
| 403 | `INSUFFICIENT_SCOPE` | 当前密钥未授权该能力；由管理员重新创建所需范围的凭证 |
| 403 | `PARTNER_SCOPE_MISMATCH` | URL 中的组织与密钥绑定组织不同 |
| 403 | `PARTNER_MANAGER_REQUIRED` | 创建者已不具备对应有效组织管理员身份 |
| 403 | `PARTNER_ACCESS_FORBIDDEN` | 工单桥接重新检查时发现组织或密钥授权已失效 |
| 403 | `PERSONAL_KEY_REQUIRED` | 组织密钥调用了个人权益接口 |
| 404 | `RECORD_NOT_FOUND` | 记录不存在或不属于此组织；不能解释为通过 |
| 404 | `INVITE_UNAVAILABLE` | 邀请不存在或不可见 |
| 404 | `TICKET_NOT_FOUND` | 工单不存在或关联校验失败 |
| 404 | `NOT_FOUND` | 未开放的路径或方法 |
| 409 | `IDEMPOTENCY_CONFLICT` | 同一请求编号对应的正文不同；查明原业务请求，不要自动换编号 |
| 409 | `PLAYER_NOT_JOINED` | 邀请尚未形成正式工单 |
| 409 | `INVITE_UNAVAILABLE` | 链接已使用、失效、撤销或状态已变化 |
| 409 | `PARTNER_INACTIVE` | 组织已归档或不支持当前操作 |
| 408 | `REQUEST_TIMEOUT` | JSON 正文未在 5 秒内读取完成；发送完整的小型请求体 |
| 413 | `BODY_TOO_LARGE` | 请求超过允许字节数 |
| 414 | `QUERY_TOO_LONG` | 查询字符串超过 2048 字符 |
| 414 | `PATH_TOO_LONG` | 路径超过 512 字符 |
| 415 | `JSON_REQUIRED` | JSON 请求的 Content-Type 不正确 |
| 415 | `CONTENT_ENCODING_UNSUPPORTED` | 不接受压缩请求体 |
| 431 | `AUTH_HEADER_TOO_LONG` | Authorization 头超过 256 字符 |
| 422 | `INVALID_RECORD_UUID` | USS 记录 UUID 格式不正确 |
| 422 | `INVALID_GAME` | game 不为 minecraft 或 fps |
| 422 | `INVALID_FIELD` | 字符串长度或字符不合法 |
| 422 | `UNKNOWN_FIELD` / `UNKNOWN_PARAMETER` | 发送了不支持的 JSON 字段或记录筛选参数 |
| 422 | `DUPLICATE_PARAMETER` | 同一查询参数被重复传入 |
| 422 | `INVALID_LIMIT` / `INVALID_PAGE` / `INVALID_CURSOR` | 分页参数错误 |
| 422 | `INVALID_DATE` / `INVALID_RESULT` | 时间或结果筛选格式错误 |
| 429 | `RATE_LIMITED` | 遵守 Retry-After 并退避 |
| 429 | `CONCURRENCY_LIMITED` | 同一密钥、组织或账号的工单请求正在处理中，排队后重试 |
| 429 | `TOO_MANY_INVITES` | 组织已有 50 个有效待加入/处理中邀请，先处理或撤销旧邀请 |
| 503 | `TICKET_SERVICE_UNAVAILABLE` | 工单服务暂不可用，稍后有限重试 |
| 503 | `RATE_LIMIT_UNAVAILABLE` | 流量保护暂不可用，按 Retry-After 重试，不要绕过保护 |
| 500 | `INTERNAL_ERROR` | 保留 request_id，有限重试后联系支持 |

工单服务也可能返回更具体的 `KOOK_RATE_LIMITED` 等上游错误码。不要在程序中只允许上表列出的错误；为未知 4xx 和 5xx 提供安全分支。

## 创建邀请时超时

保留原 API Key、组织、Idempotency-Key 和正文重试。响应恢复后保存邀请 ID。不要根据连接超时就把业务状态写成“没有创建”，也不要重新收费或为同一业务连续生成新邀请。

## 个人中心错误

个人中心使用网站会话，错误展示可能使用 `code`、`message` 顶层字段，这是网站内部协议。第三方只应实现开放 API 的 `error` 信封。

常见配置错误包括 `INVALID_PASSWORD`、`INVALID_TWO_FACTOR`、`INVALID_SCOPES`、`INVALID_EXPIRY`、`KEY_LIMIT`、`WEBHOOK_LIMIT_OR_ACCESS_CHANGED`。

## Webhook 失败

- `CHALLENGE_RESPONSE_INVALID`：接收端未返回有效且足够小的 JSON。
- `CHALLENGE_MISMATCH`：challenge 没有原样回显。
- `HTTP_3xx`：回调发生重定向，请填写最终 HTTPS 地址。
- `HTTP_4xx`：检查路由、验签原始字节、时钟和请求体大小限制。
- `HTTP_5xx`：接收端处理失败，平台会重试业务事件。
- `INVALID_WEBHOOK_URL` / `UNSAFE_WEBHOOK_DESTINATION`：地址或 DNS 未通过公网目标检查。
- `CONNECTION_FAILED` / `WEBHOOK_UNREACHABLE`：DNS、TLS、网络或超时问题。
- `ACCESS_REVOKED`：回调创建者已失权或订阅已停用，待投递被取消。

支持定位时提供事件 ID、投递状态和 request_id，不要把 API Key 或 Webhook 签名密钥发送给支持人员。