错误码与请求诊断

按协议错误和稳定错误码处理失败，使用请求编号关联服务端日志。HTTP 429 表示请求受到限流，不代表账号被封禁，也不代表设备码或验证码无效。

读取错误

KAI 自有管理 API 返回 {"error":{"code":"...","message":"...","requestId":"..."}}。Better Auth 接口在顶层返回 code、message 和 requestId。OAuth 接口保留标准 error、error_description，同时提供扩展 code、requestId。不要假设三类接口的 error 字段类型相同。

错误响应的 X-Request-ID 与正文 requestId 对应同一次服务端请求；X-Error-Code 给出稳定诊断码。界面提示有可展开、复制的错误详情。向负责人反馈时提供时间、接口路径、HTTP 状态、错误码和请求编号，不发送 Cookie、密码、验证码、授权码或令牌。

常见结果

错误码	含义与动作
`INVALID_PASSWORD`	密码不匹配，重新输入
`OTP_INCORRECT`	验证码不匹配，重新输入
`OTP_EXPIRED`	验证码已过期，获取新码
`OTP_ALREADY_USED`	验证码已使用，获取新码
`OTP_REPLACED`	旧码被新码替换，使用当前请求的新码
`AUTHENTICATION_REQUIRED`	当前请求需要登录；仅凭 401 不能判断登录状态过期
`SESSION_EXPIRED` / `SESSION_REVOKED`	已知会话过期或被撤销，重新登录
`PERMISSION_DENIED`	当前身份没有操作权限
`DEVICE_CODE_INVALID` / `DEVICE_CODE_EXPIRED`	分别为设备码无效和设备请求过期
`RATE_LIMITED`	请求受限，等待后重试并保留当前输入和设备码
`SLOW_DOWN`	设备轮询过快，增加轮询间隔
`INTERNAL_ERROR` / `SERVICE_UNAVAILABLE`	服务暂时无法完成请求，用请求编号排查
`OAUTH_GRANT_REVOKED`	原授权已失效，需要用户重新授权
`OAUTH_REAUTHENTICATION_REQUIRED`	原授权无法继续满足认证要求，需要重新交互登录

部分业务使用前缀，例如 MANAGEMENT_STEP_UP_OTP_EXPIRED。以稳定码处理已知恢复动作，不通过匹配英文 message 决定业务逻辑；未知码保留用于报障，不猜测原因。标准 OAuth invalid_grant 本身不能区分过期、撤销、重复兑换或其他授权条件，不应一律显示“密码错误”。

正确处理 429

有明确等待期限时，响应包含非负整数 retryAfterSeconds 和 Retry-After：

{
  "error": "temporarily_unavailable",
  "error_description": "Too many requests. Retry after the indicated delay.",
  "code": "RATE_LIMITED",
  "requestId": "example-request-id",
  "retryAfterSeconds": 30
}

等待指定时间再请求。没有等待期限时不要伪造倒计时，允许稍后手动重试或使用有上限的退避。设备授权页面保留当前设备码；不要把 429 显示为“代码无效”，也不要立即申请新码制造更多请求。

多个设备或应用在同一出口下的正常授权，分别按服务端授权记录计数；仍有 IP 总请求上限。密码、验证码、未知码猜测、客户端认证、PKCE 和令牌轮换保护继续生效。设备客户端必须遵守服务端的 interval，收到标准 slow_down 时增加至少 5 秒轮询间隔，见 RFC 8628 §3.5。

重试和不确定结果

服务端 5xx 与网络未收到响应不能证明写操作没有执行。邀请、保存配置、发送测试等写操作失败后先读取最新状态，确认结果再重试。账号恢复尚未完成首次归属证明时会保留中性拒绝提示，避免泄漏账号状态；不要据此推断验证码具体错误原因。

CLI 的普通输出包含错误码和请求编号，--json 可读取 error.requestId 和 error.retryAfterSeconds。退出和撤销授权的区别见退出与授权撤销。