ATKONBASE

外观

认证错误码（101*） ​

段位：101001 - 101023 中对外集成可命中 15 个 —— V1 暴露 12 个（101001-101011 + 101015）+ Identity Broker 授权码兑换 3 个（101020-101022，经官方 SDK oauth.exchangeCode 命中）；101012-101014、101016 仅在管理端等非 V1 集成路径触发，101017-101019、101023 仅在 /oauth 浏览器交互流程内部使用，均不在本参考之列

通用约定（HTTP status / code=1 兜底 / 响应结构）见 README

101001 AUTHENTICATION_FAILED ​

  • HTTP status：200
  • 含义：未登录 / Token 无效
  • 典型触发条件：未携带 Authorization Header；或 Bearer token 已过期 / 已被吊销 / 格式错误
  • 处理建议：调用 /v1/auth/token 重新获取 access token；若使用 refreshToken 刷新失败，必须重新走 client credentials 流程
  • 示例响应：
json
{ "code": 101001, "msg": "认证失败", "data": null }

101002 CLIENT_CREDENTIALS_INVALID ​

  • HTTP status：200
  • 含义：Client 凭证错误
  • 典型触发条件：调用 /v1/auth/token 时 clientId 或 clientSecret 不正确（不存在、被改、笔误）
  • 处理建议：核对 Console「API 客户端」面板中的 clientId 与 clientSecret；切勿把 secret 入仓——若怀疑泄露，立即在 Console 重置
  • 示例响应：
json
{ "code": 101002, "msg": "Client 凭证错误", "data": null }

101003 CLIENT_DISABLED ​

  • HTTP status：200
  • 含义：Client 已禁用
  • 典型触发条件：API Client 已被管理员在 Console 禁用
  • 处理建议：联系租户管理员在 Console 启用该 API Client；本错误不可由集成方端自助解决
  • 示例响应：
json
{ "code": 101003, "msg": "Client 已禁用", "data": null }

101004 CREDENTIALS_EXPIRED ​

  • HTTP status：200
  • 含义：登录凭证 / 刷新令牌已过期
  • 典型触发条件：refreshToken 已过期，或登录会话 TTL 到期
  • 处理建议：重新调用 /v1/auth/token 走 client credentials 流程取新 token
  • 示例响应：
json
{ "code": 101004, "msg": "登录凭证已过期", "data": null }

101005 GRANT_TYPE_UNSUPPORTED ​

  • HTTP status：200
  • 含义：不支持的 grantType
  • 典型触发条件：使用了 V1 通道不支持的授权模式（V1 通道当前仅支持 client credentials 与少数受控扩展）
  • 处理建议：检查请求形态——V1 集成 API 应直接 POST {clientId, clientSecret} 到 /v1/auth/token，无需指定 grantType
  • 示例响应：
json
{ "code": 101005, "msg": "不支持的 grantType", "data": null }

101006 GRANT_PARAMS_MISMATCH ​

  • HTTP status：200
  • 含义：Grant 参数类型不匹配
  • 典型触发条件：使用了某种 grant 但参数组合不完整（如 password grant 缺 username/password）
  • 处理建议：参考具体 grant 类型对应文档（多数集成方走 client credentials 即可，不会命中此错误）
  • 示例响应：
json
{ "code": 101006, "msg": "Grant 参数类型不匹配", "data": null }

101007 TENANT_ACCESS_DENIED ​

  • HTTP status：200
  • 含义：无权登录该租户
  • 典型触发条件：用户凭证试图登录非其归属的租户
  • 处理建议：确认凭据归属的 tenantId；多租户场景下不可跨租户复用凭据
  • 示例响应：
json
{ "code": 101007, "msg": "无权登录该租户", "data": null }

101008 INVALID_DELEGATION_HEADERS ​

  • HTTP status：400
  • 含义：双通道委派头互斥（同时携带 X-Atk-User-Token + X-Atk-Act-As-Source*）
  • 典型触发条件：请求同时携带强通道（X-Atk-User-Token）与弱通道（X-Atk-Act-As-Source / X-Atk-Act-As-Source-Id）的 Header
  • 处理建议：二选一——确定是强通道用 X-Atk-User-Token，弱通道用 X-Atk-Act-As-Source + X-Atk-Act-As-Source-Id 配对；具体选择规则见认证与身份双通道模式篇
  • 示例响应：
json
{ "code": 101008, "msg": "双通道委派头互斥", "data": null }

101009 INCOMPLETE_ACT_AS_HEADERS ​

  • HTTP status：400
  • 含义：弱通道双头不成对
  • 典型触发条件：请求只携带 X-Atk-Act-As-Source 或只携带 X-Atk-Act-As-Source-Id，但弱通道必须两个都出现
  • 处理建议：补齐缺失的 Header；若是误带，删除已携带的那一个
  • 示例响应：
json
{ "code": 101009, "msg": "X-Atk-Act-As-Source 与 X-Atk-Act-As-Source-Id 必须同时出现", "data": null }

101010 USER_TOKEN_INVALID ​

  • HTTP status：401
  • 含义：强通道 user_token 失效（统一不区分原因细节：过期 / 已登出 / 已被踢出 / 签名失败）
  • 典型触发条件：X-Atk-User-Token 头部携带的 user token 已不可用
  • 处理建议：让对应的最终用户重新登录获取新 user_token。本错误不区分具体失效原因，处理方式统一为重新登录
  • 示例响应：
json
{ "code": 101010, "msg": "user_token 失效", "data": null }

101011 CROSS_TENANT_VIOLATION ​

  • HTTP status：403
  • 含义：跨租户违规——委派用户与调用的 API Client 不属于同一租户
  • 典型触发条件：强通道 / 弱通道委派的用户租户与 API Client 自身租户不一致
  • 处理建议：核对委派用户的归属租户——atkonbase 默认禁止跨租户委派；确需跨租户场景须走专门流程
  • 示例响应：
json
{ "code": 101011, "msg": "跨租户违规", "data": null }

101015 V1_ACL_USER_IDENTITY_REQUIRED ​

  • HTTP status：200
  • 含义：V1 ACL 端点需双通道下发用户身份
  • 典型触发条件：用 client-only（APP_ONLY）凭证调用 /v1/acl/* 端点，但未通过 X-Atk-User-Token（强通道）或 X-Atk-Act-As-Source*（弱通道 act-as）下发最终用户身份——ACL 是以用户为主体的访问控制，缺用户身份无法判定
  • 处理建议：调用 /v1/acl/* 前，按认证与身份双通道模式篇携带用户委派头（X-Atk-User-Token 或 act-as 双头配对）
  • 示例响应：
json
{ "code": 101015, "msg": "ACL 端点需要 X-Atk-User-Token 或 act-as 双通道下发用户身份", "data": null }

Identity Broker 授权码兑换（101020-101022） ​

以下错误码在用授权码兑换访问凭证时由集成方后端收到——即官方 SDK 的 oauth.exchangeCode（底层 POST /oauth/token）。授权码流的完整接入见 Identity Broker 接入指南；浏览器交互阶段（authorize / 托管登录页）的内部信号码不在此列。

101020 BROKER_AUTH_CODE_INVALID ​

  • HTTP status：200
  • 含义：授权码无效、已过期或已被兑换
  • 典型触发条件：用不存在、已过期（授权码分钟级失效）或已被兑换过（一次性消费、兑换后即失效）的授权码 code 兑换访问凭证——例如重复用同一个 code 兑换、或回跳后延迟过久才兑换
  • 处理建议：授权码仅一次性、分钟级有效，回跳后立即兑换，勿缓存或对同一个 code 重试；需要新凭证时重新发起授权（oauth.buildAuthorizeUrl）
  • 示例响应：
json
{ "code": 101020, "msg": "授权码无效、已过期或已被兑换", "data": null }

101021 BROKER_PKCE_VERIFICATION_FAILED ​

  • HTTP status：200
  • 含义：授权码兑换 PKCE 校验失败
  • 典型触发条件：兑换请求缺 code_verifier，或 code_verifier 与发起授权时的 code_challenge 不匹配——常见于两步用了不同的 verifier，或会话里暂存的 code_verifier 丢失 / 串号
  • 处理建议：兑换时回传与发起授权同一会话生成的 code_verifier；用 SDK oauth.buildAuthorizeUrl + oauth.exchangeCode 配对会自动暂存与回传 PKCE 串，勿手动改写
  • 示例响应：
json
{ "code": 101021, "msg": "PKCE 校验失败", "data": null }

101022 BROKER_REDIRECT_URI_MISMATCH ​

  • HTTP status：200
  • 含义：授权码兑换时回调地址与签发记录绑定的回调地址不一致
  • 典型触发条件：兑换传入的 redirectUri 与发起授权时的 redirect_uri 不逐字一致（精确匹配：协议 / 主机 / 路径 / 查询都要相同）
  • 处理建议：发起授权与兑换使用同一个登记过的回调地址常量，勿动态拼查询串；多环境 / 多入口各自登记独立 Client，详见 Identity Broker 接入指南
  • 示例响应：
json
{ "code": 101022, "msg": "回调地址与签发记录不一致", "data": null }