错误码参考

受众：集成开发者
阅读路径：拿到 V1 错误响应时，按响应中的 code 字段段位（如 101001）打开对应业务域文件查含义、典型触发条件、处理建议。
本参考收录 V1 集成 API 可能返回的错误码。仅在 Console、公开分享（/public/*）等非 V1 路径触发的错误码不在此列，见末尾不在本参考范围的错误码。

错误响应结构

V1 所有业务接口（不论成败）统一返回 ResponseDTO<T> 结构：

json

{
  "code": 101001,
  "msg": "认证失败",
  "data": null
}

字段	类型	说明
`code`	int	业务状态码。`0` 表成功；非 0 表失败
`msg`	string	提示文本（业务异常的描述，或成功时的 "操作成功"）
`data`	T or null	成功时携带业务数据；失败时通常为 null

HTTP status：统一 200（V1 业务错）

⚠️ atkonbase V1 不通过 HTTP status 区分业务错——所有业务异常均返 HTTP 200，业务结果由 body.code 区分。
集成方代码不可按 HTTP status 判断业务成败，必须读 body.code。

少数非业务码的 HTTP 错误保留原始状态码，作为「附录」单独列在本页末尾。

唯一例外的业务码是检索不可用 176001：它是业务码却以 HTTP 503 返回（body 仍是 ResponseDTO），以便按标准 HTTP 语义退避重试。除此之外 V1 业务错一律 200。

`code=1` 兜底分支必须保留

⚠️ V1 还可能返回 code=1 通用错，涵盖以下场景，集成方代码必须保留 code=1 + msg 兜底分支，不可做枚举式 exhaustive switch：
未指定错误码的业务异常：服务端相当一部分业务异常未指定具体错误码——这类以默认 code=1 返回
请求参数缺失 / 类型不匹配：由服务端对缺参 / 类型不匹配等统一兜底
数据完整性校验失败：数据约束等问题被兜底
未编码业务错 / 其它未识别错误：服务端对未识别的错误统一返回 code=1
这些情况下 code 一律是 1，msg 携带具体原因文本。

错误码业务域分组

业务域	段位	文件	数量
认证	101*	auth-101	12
权限	102*	permission-102	11
用户	103*	user-103	1
Principal 同步	104*	principal-sync-104	2
IdP / SSO	105*	idp-sso-105	15
API Client / Scope	106*	api-client-106	9
业务身份	112*	business-identity-112	13
存储	173*	storage-173	18
Share	174*	share-174	34
容器	175*	container-175	27
检索	176*	search-176	2
Webhook	177*	integration-177	6
系统维护	178*	setting-178	1
文件上传 / 下载	179*	file-179	24
摄入	181*	ingest-181	3
元数据	182*	metadata-182	22
内容类型	183*	contenttype-183	4
文档	185*	document-185	17
内容 ACL	186*	contentacl-186	7
资源访问	187*	access-187	4
合计	—	—	232

注：认证段 12 项含 V1 暴露码 101015（V1 ACL 端点需委派用户身份）。
存储 173* 与文件 179* 同覆盖上传 / 下载链路（173* 为存储层会话 / 配额 / 直读，179* 为上传业务校验）；存储 173* 与摄入 181* 同覆盖摄入链路（173* 为存储层 URL / 对象校验，181* 为摄入目标 / 任务校验）。

不在本参考范围的错误码

以下错误码仅在非 V1 路径触发，V1 集成 API 不会返回，故本参考不收录：

Console 管理端与外部目录同步专用错误码：仅在 Console 管理端点、外部目录同步等路径触发。

附录：非业务码的 HTTP 错误（保留原始状态码）

除上述统一以 HTTP 200 + 业务 code 返回的业务错误外，少数请求会在到达业务层之前或之后被底层拦截，返回非 200 的原始 HTTP 状态码，且响应 body 可能不是 ResponseDTO 结构。这类错误不在 V1 业务错误码清单内：

HTTP status	触发条件	处理建议
401 / 403	token 未携带 / 已失效，或鉴权、权限校验在业务层之前失败。注意：多数鉴权 / 权限失败已以 HTTP 200 + 业务 code 返回（见 101* / 102* 段），仅少数未被业务层接住的情况才保留原始 401 / 403	重新调用 `/v1/auth/token` 获取新 token；若 token 形态正确仍失败，核对 `Authorization` Header 拼写与 `Bearer` 前缀
404	请求路径未匹配任何端点	检查 URL 拼写与版本前缀 `/v1`
413	上传单请求体积超过传输层上限	改走分片上传链路（`/v1/versions/initChunkedUpload`），或联系部署方调高上限
415	请求 Content-Type 不被端点接受	检查请求 header；JSON 端点需 `application/json`，multipart 端点需 `multipart/form-data`
500	服务端未预期的错误	携带响应中的 `rid` / `X-Request-Id` 联系 ATKONBASE 支持团队

这类错误的响应 body 形态可能不是 ResponseDTO 结构。集成方建议在 HTTP 客户端层先按状态码做粗筛：>= 400 走错误路径，再尝试解析 body；解析不到 ResponseDTO 时按 HTTP status 文案展示。

错误码参考 ​

错误响应结构 ​

HTTP status：统一 200（V1 业务错） ​

code=1 兜底分支必须保留 ​

错误码业务域分组 ​

不在本参考范围的错误码 ​