ATKONBASE

外观

文件上传 / 下载错误码（179*） ​

段位：179001 - 179999；当前 24 个（179001 - 179024）；全部 V1 暴露

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

经 V1 /v1/versions/* 上传 / 下载链路暴露：直接上传（upload）、分片上传（initChunkedUpload / uploadChunk / completeChunkedUpload）、预签名直传（presign-upload / finalize-upload）、签名直读（signed-url）、下载（download）。

上传 / 下载链路还会返回存储侧的 存储错误码 173*（预签名会话 / 配额 / 签名直读 / 分片会话不存在）。

上传目标 ​

179001 UPLOAD_TARGET_AMBIGUOUS ​

  • HTTP status：200
  • 含义：上传目标二选一冲突
  • 典型触发条件：同时提供了 docId（向已有文档追加版本）与 containerId + title（新建文档）
  • 处理建议：二选一——追加版本只传 docId；新建文档只传 containerId + title
  • 示例响应：
json
{ "code": 179001, "msg": "上传目标二选一：docId 与 containerId+title 不能同时提供", "data": null }

179002 UPLOAD_TARGET_REQUIRED ​

  • HTTP status：200
  • 含义：上传目标缺失
  • 典型触发条件：既未提供 docId，也未提供 containerId + title
  • 处理建议：提供 docId（已有文档）或 containerId + title（新建文档）之一
  • 示例响应：
json
{ "code": 179002, "msg": "上传目标缺失：需提供 docId 或 containerId+title", "data": null }

分片上传会话 ​

179003 UPLOAD_IDEMPOTENCY_KEY_REQUIRED ​

  • HTTP status：200
  • 含义：分片上传初始化缺少 idempotencyKey
  • 典型触发条件：initChunkedUpload 未提供 idempotencyKey
  • 处理建议：分片上传初始化须提供 idempotencyKey（用于幂等去重与断点续传）
  • 示例响应：
json
{ "code": 179003, "msg": "缺少 idempotencyKey", "data": null }

179004 UPLOAD_IN_PROGRESS ​

  • HTTP status：200
  • 含义：同一幂等键的上传仍在处理中
  • 典型触发条件：同一 idempotencyKey 的上传处于初始化 / 上传中，又重复提交
  • 处理建议：复用既有会话续传，勿对同一幂等键重复初始化
  • 示例响应：
json
{ "code": 179004, "msg": "上传仍在处理中，请勿重复提交", "data": null }

179005 UPLOAD_IDEMPOTENCY_CONFLICT ​

  • HTTP status：200
  • 含义：幂等键冲突
  • 典型触发条件：复用到的会话上下文与本次请求不一致，或会话处于异常状态
  • 处理建议：换用新的 idempotencyKey 重新初始化上传
  • 示例响应：
json
{ "code": 179005, "msg": "幂等键冲突", "data": null }

179006 UPLOAD_SESSION_KIND_MISMATCH ​

  • HTTP status：200
  • 含义：会话类型不是分片上传
  • 典型触发条件：对非分片会话调用 uploadChunk / completeChunkedUpload
  • 处理建议：核对 uploadId 来源；分片端点仅受理分片会话
  • 示例响应：
json
{ "code": 179006, "msg": "会话类型不匹配", "data": null }

179007 UPLOAD_SESSION_COMPLETED ​

  • HTTP status：200
  • 含义：会话已完成
  • 典型触发条件：对已完成的会话再上传分片
  • 处理建议：会话完成后不再受理新分片；如需重传请重新初始化
  • 示例响应：
json
{ "code": 179007, "msg": "会话已完成", "data": null }

179008 UPLOAD_SESSION_ABORTED ​

  • HTTP status：200
  • 含义：会话已中止
  • 典型触发条件：对已中止的会话继续上传
  • 处理建议：重新初始化分片上传后再传
  • 示例响应：
json
{ "code": 179008, "msg": "会话已中止，请重新初始化", "data": null }

分片校验 ​

179009 CHUNK_INDEX_OUT_OF_RANGE ​

  • HTTP status：200
  • 含义：分片序号超出范围
  • 典型触发条件：分片序号超过会话声明的总分片数
  • 处理建议：分片序号须在 [0, totalChunks) 内
  • 示例响应：
json
{ "code": 179009, "msg": "分片序号超出范围", "data": null }

179010 CHUNK_SIZE_MISMATCH ​

  • HTTP status：200
  • 含义：分片大小不一致
  • 典型触发条件：分片实际大小与请求 / 会话声明（含最后一片推算值）不符
  • 处理建议：按初始化时约定的分片大小切分上传，最后一片为剩余字节
  • 示例响应：
json
{ "code": 179010, "msg": "分片大小不一致", "data": null }

179011 CHUNK_SIZE_EXCEEDS_LIMIT ​

  • HTTP status：200
  • 含义：单分片大小超限
  • 典型触发条件：单个分片超过 50MB 上限
  • 处理建议：将分片大小控制在 50MB 以内
  • 示例响应：
json
{ "code": 179011, "msg": "单分片大小超过 50MB", "data": null }

179012 CHUNK_HASH_MISMATCH ​

  • HTTP status：200
  • 含义：分片哈希不一致
  • 典型触发条件：分片内容哈希与客户端声明的 chunkHash 不符
  • 处理建议：重传该分片；确认计算哈希的字节与实际上传字节一致
  • 示例响应：
json
{ "code": 179012, "msg": "分片哈希不一致", "data": null }

179013 CHUNK_INCOMPLETE ​

  • HTTP status：200
  • 含义：分片不完整
  • 典型触发条件：completeChunkedUpload 时缺少某个分片序号
  • 处理建议：补齐缺失分片后再完成；可据返回提示定位缺失序号
  • 示例响应：
json
{ "code": 179013, "msg": "分片不完整，存在缺失", "data": null }

179014 CONTENT_HASH_MISMATCH ​

  • HTTP status：200
  • 含义：合并后内容哈希不一致
  • 典型触发条件：分片合并后的整体哈希与会话声明的 expectedContentHash 不符（分片可能损坏）
  • 处理建议：重新上传该文件
  • 示例响应：
json
{ "code": 179014, "msg": "内容哈希不一致，请重新上传", "data": null }

179015 CHUNKED_INIT_PARAMS_INVALID ​

  • HTTP status：200
  • 含义：分片初始化参数非法
  • 典型触发条件：totalSize / chunkSize / totalChunks 取值或互相约束不成立
  • 处理建议：确保三者自洽：totalChunks = ceil(totalSize / chunkSize)
  • 示例响应：
json
{ "code": 179015, "msg": "分片初始化参数非法", "data": null }

179016 UPLOAD_SESSION_OWNERSHIP_MISMATCH ​

  • HTTP status：200
  • 含义：操作者与会话归属不一致
  • 典型触发条件：用一个身份初始化会话、却用另一身份续传 / 完成。出于安全考虑，归属不一致与会话不存在返回同一错误码
  • 处理建议：保证分片上传全程由同一身份发起
  • 示例响应：
json
{ "code": 179016, "msg": "会话归属不一致", "data": null }

下载 / 直读 ​

179017 VERSION_HAS_NO_FILE ​

  • HTTP status：200
  • 含义：版本未关联文件
  • 典型触发条件：对一个 blobId 为空的版本下载 / 签发直读 URL
  • 处理建议：仅对已关联文件的版本下载；确认该版本确有上传内容
  • 示例响应：
json
{ "code": 179017, "msg": "版本未关联文件", "data": null }

179018 FILE_NOT_READY ​

  • HTTP status：200
  • 含义：文件暂不可用
  • 典型触发条件：版本关联的文件尚未处于就绪状态（如直传 finalize / 摄入尚未完成）
  • 处理建议：稍后重试；异步摄入完成后会通过 document.updated Webhook 通知
  • 示例响应：
json
{ "code": 179018, "msg": "文件暂不可用", "data": null }

上传约束 ​

179019 UPLOAD_FILE_SIZE_EXCEEDS_LIMIT ​

  • HTTP status：200
  • 含义：文件大小超出租户上传限制
  • 典型触发条件：上传文件超过租户配置的单文件大小上限
  • 处理建议：压缩 / 分拆内容，或联系部署方调高上限
  • 示例响应：
json
{ "code": 179019, "msg": "文件大小超出上传限制", "data": null }

179020 UPLOAD_MIME_TYPE_DENIED ​

  • HTTP status：200
  • 含义：文件类型命中上传黑名单
  • 典型触发条件：文件 MIME 类型在上传黑名单内，被禁止上传
  • 处理建议：核对租户允许的文件类型策略；该类型被显式禁止
  • 示例响应：
json
{ "code": 179020, "msg": "文件类型被禁止上传", "data": null }

179021 UPLOAD_MIME_TYPE_NOT_ALLOWED ​

  • HTTP status：200
  • 含义：文件类型不在上传白名单
  • 典型触发条件：白名单非空时，文件 MIME 类型不在允许列表内
  • 处理建议：仅上传白名单内的文件类型；如需放开，由部署方调整租户上传策略
  • 示例响应：
json
{ "code": 179021, "msg": "文件类型不在允许列表内", "data": null }

元数据（随上传） ​

179022 METADATA_VALIDATION_FAILED ​

  • HTTP status：200
  • 含义：新建文档时元数据校验失败
  • 典型触发条件：上传新建文档时携带的元数据校验未通过（必填缺失 / 取值不合法）
  • 处理建议：按目标内容类型的字段约束修正元数据后重试；字段级细分校验另见 元数据错误码 182*
  • 示例响应：
json
{ "code": 179022, "msg": "元数据校验失败", "data": null }

179023 METADATA_JSON_MALFORMED ​

  • HTTP status：200
  • 含义：元数据 JSON 解析失败
  • 典型触发条件：上传携带的元数据 JSON 格式错误
  • 处理建议：确认元数据为合法 JSON 后重试
  • 示例响应：
json
{ "code": 179023, "msg": "元数据 JSON 格式错误", "data": null }

179024 DOCUMENT_STATE_NOT_UPLOADABLE ​

  • HTTP status：200
  • 含义：目标文档状态不可上传新版本
  • 典型触发条件：目标文档非 ACTIVE（归档 / 回收站等），不能在其上新建版本
  • 处理建议：先把文档恢复到 ACTIVE 再上传新版本
  • 示例响应：
json
{ "code": 179024, "msg": "文档状态不可上传新版本", "data": null }