ATKONBASE

外观

认证错误码（101*） ​

段位：101001 - 101015 中 V1 暴露 12 个（101001-101011 + 101015）；101012-101014、101016 仅在管理端等非 V1 集成路径触发，不在本参考之列

通用约定（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 }