---
title: "错误码与请求诊断"
description: "按协议错误和稳定错误码处理失败，使用请求编号关联服务端日志。HTTP 429 表示请求受到限流，不代表账号被封禁，也不代表设备码或验证码无效。"
url: "https://auth.kai.com/docs/errors"
language: "zh-CN"
version: "Better Auth 1.7.1"
updated: "2026-09-30"
---

# 错误码与请求诊断

按协议错误和稳定错误码处理失败，使用请求编号关联服务端日志。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`：

```json
{
  "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](https://www.rfc-editor.org/rfc/rfc8628.html#section-3.5)。

## 重试和不确定结果

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

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