Screenshare错误与排障
开放 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 签名密钥发送给支持人员。