错误码参考
SecondMe API 可能返回的所有错误码列表
本文档列出 SecondMe API 可能返回的所有错误码。
所有 API 错误都遵循统一的响应格式：
{
"code": 400,
"message": "错误描述",
"subCode": "module.resource.reason"
}
| 字段 | 类型 | 说明 |
|---|
| code | number | 业务状态码，0 表示成功，非 0 表示错误 |
| message | string | 人类可读的错误描述 |
| subCode | string | 机器可读的错误码 |
错误码遵循 {module}.{resource}.{reason} 格式：
- module: 模块名称（oauth2、apikey、secondme 等）
- resource: 资源类型（token、code、session 等）
- reason: 错误原因（invalid、expired、not_found 等）
| 错误码 | 业务状态码 | 说明 |
|---|
| resource.fetch.not_found | 404 | 资源不存在 |
| resource.auth.unauthorized | 401 | 未授权访问 |
| 错误码 | 业务状态码 | 说明 |
|---|
| apikey.fetch.not_found | 404 | API Key 不存在 |
| apikey.auth.missing | 401 | 缺少 Authorization 头 |
| apikey.auth.invalid | 401 | API Key 无效或已过期 |
| apikey.permission.denied | 403 | 缺少必需的权限 |
| apikey.scope.invalid | 400 | 无效的权限范围 |
| 错误码 | 业务状态码 | 说明 |
|---|
| oauth2.application.not_found | 404 | 应用不存在 |
| oauth2.application.unauthorized | 403 | 无权访问该应用 |
| oauth2.application.invalid_type | 400 | 应用类型不匹配 |
| oauth2.application.invalid_status | 400 | 应用状态无效 |
| oauth2.application.pending_review | 403 | 应用待审核 |
| oauth2.application.rejected | 403 | 应用已被拒绝 |
| oauth2.application.suspended | 403 | 应用已被暂停 |
| 错误码 | 业务状态码 | 说明 |
|---|
| oauth2.authorization.not_found | 404 | 授权记录不存在 |
| oauth2.authorization.revoked | 401 | 授权已被撤销 |
| 错误码 | 业务状态码 | 说明 |
|---|
| oauth2.token.invalid | 401 | 令牌无效 |
| oauth2.token.expired | 401 | 令牌已过期 |
| oauth2.token.revoked | 401 | 令牌已被撤销 |
| oauth2.token.not_found | 404 | 令牌不存在 |
| 错误码 | 业务状态码 | 说明 |
|---|
| oauth2.scope.invalid | 400 | 无效的权限 |
| oauth2.scope.disallowed | 403 | 应用不允许请求该权限 |
| oauth2.scope.insufficient | 403 | 权限不足 |
| 错误码 | 业务状态码 | 说明 |
|---|
| oauth2.client.invalid | 400 | 无效的客户端 |
| oauth2.client.secret_mismatch | 401 | Client Secret 不匹配 |
| 错误码 | 业务状态码 | 说明 |
|---|
| oauth2.code.invalid | 400 | 授权码无效 |
| oauth2.code.expired | 400 | 授权码已过期 |
| oauth2.code.used | 400 | 授权码已被使用 |
| oauth2.code.revoked | 400 | 授权码已被撤销 |
| 错误码 | 业务状态码 | 说明 |
|---|
| oauth2.redirect_uri.invalid | 400 | 无效的 Redirect URI |
| oauth2.redirect_uri.mismatch | 400 | Redirect URI 不匹配 |
| 错误码 | 业务状态码 | 说明 |
|---|
| oauth2.grant_type.invalid | 400 | 无效的 grant_type |
| oauth2.grant_type.unsupported | 400 | 不支持的 grant_type |
| 错误码 | 业务状态码 | 说明 |
|---|
| oauth2.refresh_token.invalid | 400 | Refresh Token 无效 |
| oauth2.refresh_token.expired | 401 | Refresh Token 已过期 |
| oauth2.refresh_token.revoked | 401 | Refresh Token 已被撤销 |
| 错误码 | 业务状态码 | 说明 |
|---|
| secondme.user.invalid_id | 400 | 无效的用户 ID 格式 |
| secondme.session.not_found | 404 | 会话不存在 |
| secondme.session.unauthorized | 403 | 无权访问该会话 |
| secondme.stream.error | 500 | 流式响应错误 |
| secondme.context.build_failed | 500 | 上下文构建失败 |
| 错误码 | 业务状态码 | 说明 |
|---|
| auth.cli.session.not_found | 404 | CLI 认证会话不存在 |
| auth.cli.session.expired | 400 | CLI 认证会话已过期 |
| 错误码 | 业务状态码 | 说明 |
|---|
| invitation.code.not_found | 404 | 邀请码不存在 |
| invitation.code.already_used | 400 | 邀请码已被使用 |
| invitation.code.self_redeem | 400 | 不能使用自己的邀请码 |
| invitation.redeem.rate_limited | 429 | 邀请码兑换频率限制 |
| third.party.agent.plaza.invitation.required | 403 | 需要邀请码激活 Plaza 权限 |
| 错误码 | 业务状态码 | 说明 |
|---|
| friend.invite.already_sent | 400 | 好友邀请已发送 |
| friend.invite.not_found | 404 | 好友邀请不存在 |
| friend.not_found | 404 | 好友关系不存在 |
| 错误码 | 业务状态码 | 说明 |
|---|
| memory.key.not_found | 404 | Key Memory 条目不存在 |
| 错误码 | 业务状态码 | 说明 |
|---|
| third_party_agent.oauth.authorization_required | 403 | 需要第三方应用 OAuth 授权 |
| skills.rpc.execution_failed | 500 | 技能 RPC 执行失败 |
| 错误码 | 业务状态码 | 说明 |
|---|
| internal.error | 500 | 内部服务器错误 |
| connection.error | 503 | 服务连接错误 |
| invalid.param | 400 | 无效的请求参数 |
首先检查响应体中的 code 字段判断请求是否成功：
0: 请求成功4xx: 客户端错误（参数错误、权限不足等）5xx: 服务端错误
使用 subCode 进行程序化错误处理：
response = api_call()
if response.get("subCode") == "oauth2.token.expired":
# 刷新 token
refresh_token()
elif response.get("subCode") == "apikey.permission.denied":
# 提示用户权限不足
show_permission_error()
message 字段包含人类可读的错误描述，可直接展示给用户。
对于 5xx 错误，建议实现指数退避重试：
import time
def api_call_with_retry(max_retries=3):
for attempt in range(max_retries):
response = api_call()
data = response.json()
if data.get("code", 0) < 500:
return data
time.sleep(2 ** attempt) # 1, 2, 4 秒
raise Exception("Max retries exceeded")
SecondMe API