ATKONBASE

外观

存储错误码（173*） ​

段位：173001 - 173999；当前 18 个；全部 V1 暴露

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

覆盖文件落库的存储层链路：预签名直传（/v1/versions/presign-upload / /v1/versions/finalize-upload）、签名直读（/v1/versions/signed-url 及其下载 ticket 分支）、服务端摄入的存储侧校验（/v1/ingest/register-object / /v1/ingest/from-url）、分片上传会话。文件上传 / 下载链路另会返回 文件错误码 179*；摄入链路另会返回 摄入错误码 181*。

预签名直传 173001 - 173008 ​

经 POST /v1/versions/presign-upload 取直传地址、客户端 PUT 后再调 POST /v1/versions/finalize-upload 登记版本。

173001 PRESIGNED_SESSION_NOT_FOUND ​

  • HTTP status：200
  • 含义：预签名上传会话不存在
  • 典型触发条件：finalize-upload 携带的 sessionId 查无对应会话——会话从未创建、或已超期被清理
  • 处理建议：重新调用 presign-upload 取得新的会话与直传地址，再完成 PUT 与 finalize
  • 示例响应：
json
{ "code": 173001, "msg": "预签名会话不存在", "data": null }

173002 PRESIGNED_SESSION_KIND_MISMATCH ​

  • HTTP status：200
  • 含义：会话类型不匹配
  • 典型触发条件：finalize-upload 仅受理预签名类型的会话，传入的 sessionId 指向其它上传方式（如分片上传）的会话
  • 处理建议：核对 sessionId 来源；预签名直传与分片上传的会话不可混用 finalize 端点
  • 示例响应：
json
{ "code": 173002, "msg": "会话类型不匹配", "data": null }

173003 PRESIGNED_SESSION_EXPIRED ​

  • HTTP status：200
  • 含义：预签名上传会话已过期
  • 典型触发条件：客户端 PUT 与 finalize-upload 发生在 presign-upload 返回的有效期之后
  • 处理建议：缩短「取地址→PUT→finalize」的整体耗时；超期后重新 presign-upload
  • 示例响应：
json
{ "code": 173003, "msg": "预签名会话已过期", "data": null }

173004 PRESIGNED_SESSION_TERMINATED ​

  • HTTP status：200
  • 含义：会话已处于终态
  • 典型触发条件：会话已被中止 / 完成等终态，finalize-upload 不再受理
  • 处理建议：重新发起一次预签名直传；不要对已结束的会话重复 finalize
  • 示例响应：
json
{ "code": 173004, "msg": "会话已结束", "data": null }

173005 PRESIGNED_SESSION_OWNERSHIP_MISMATCH ​

  • HTTP status：200
  • 含义：操作者与会话归属不一致
  • 典型触发条件：用一个身份创建会话、却用另一身份 finalize
  • 处理建议：保证 presign-upload 与 finalize-upload 由同一身份发起
  • 示例响应：
json
{ "code": 173005, "msg": "会话归属不一致", "data": null }

173006 PRESIGNED_OBJECT_NOT_FOUND_ON_PROVIDER ​

  • HTTP status：200
  • 含义：finalize 时目标对象不存在
  • 典型触发条件：客户端未实际完成 PUT、或 PUT 到了错误地址，导致 finalize 时存储中查无该对象
  • 处理建议：确认 PUT 已返回成功且使用的是 presign-upload 返回的完整地址，再调 finalize
  • 示例响应：
json
{ "code": 173006, "msg": "对象不存在", "data": null }

173007 PRESIGNED_OBJECT_SIZE_MISMATCH ​

  • HTTP status：200
  • 含义：实测对象大小与会话声明不一致
  • 典型触发条件：presign-upload 阶段声明的大小与最终 PUT 的字节数不符
  • 处理建议：以真实文件大小发起 presign-upload；中途内容变化需重新取地址
  • 示例响应：
json
{ "code": 173007, "msg": "对象大小不匹配", "data": null }

173008 TENANT_QUOTA_EXCEEDED ​

  • HTTP status：200
  • 含义：租户存储配额超限
  • 典型触发条件：presign-upload 预检或 finalize-upload 二次校验时，本次上传将使租户存储用量超过配额
  • 处理建议：清理无用版本 / 文档释放空间，或联系部署方调高配额后重试
  • 示例响应：
json
{ "code": 173008, "msg": "存储配额超限", "data": null }

签名直读消费侧 173009 - 173011 ​

经 POST /v1/versions/signed-url 签发一次性直读链接，及其 fallback 的下载 ticket 分支。

173009 SIGNED_URL_EXPIRES_OUT_OF_RANGE ​

  • HTTP status：200
  • 含义：请求的有效期超出允许范围
  • 典型触发条件：signed-url 请求的 expiresInSec 不在 [1, 3600] 闭区间内（默认 300、上限 3600）
  • 处理建议：将 expiresInSec 限制在 1 - 3600 秒内；不传则用默认 300 秒
  • 示例响应：
json
{ "code": 173009, "msg": "有效期超出允许范围", "data": null }

173010 SIGNED_TICKET_INVALID ​

  • HTTP status：200
  • 含义：下载 ticket 校验失败
  • 典型触发条件：fallback 下载分支携带的 signedTicket 不存在、与目标 versionId 不匹配、或已被消费。出于安全考虑，本码不区分具体失效原因（不存在 / 不匹配 / 已消费）
  • 处理建议：重新调用 signed-url 取得新链接 / ticket；ticket 为一次性，勿复用
  • 示例响应：
json
{ "code": 173010, "msg": "下载票据无效", "data": null }

173011 PREVIEW_MIME_NOT_ALLOWED ​

  • HTTP status：200
  • 含义：preview 模式下文件类型不在白名单
  • 典型触发条件：以 mode=preview 请求直读，但版本的 MIME 类型不在预览白名单内（如 image/svg+xml 被显式排除）
  • 处理建议：改用 mode=download 获取该文件；preview 仅对受支持的可安全内联渲染的类型开放
  • 示例响应：
json
{ "code": 173011, "msg": "该类型不支持预览", "data": null }

服务端摄入存储侧 173012 - 173017 ​

经 POST /v1/ingest/register-object（登记已在存储中的对象）与 POST /v1/ingest/from-url（从外部 URL 拉取）触发的存储层校验。

173012 INGEST_OBJECT_KEY_NOT_IN_TENANT_NAMESPACE ​

  • HTTP status：200
  • 含义：登记的对象不在本租户命名空间内
  • 典型触发条件：register-object 提交的对象 key 不落在请求租户的命名空间前缀下，因此被拒绝登记
  • 处理建议：仅登记本租户命名空间下（带外迁移 / 预签名直传放入）的对象 key
  • 示例响应：
json
{ "code": 173012, "msg": "对象不属于当前租户命名空间", "data": null }

173013 INGEST_OBJECT_NOT_FOUND_ON_PROVIDER ​

  • HTTP status：200
  • 含义：登记时对象在存储中不存在
  • 典型触发条件：register-object 提交的对象 key 在存储中查无对应对象
  • 处理建议：确认对象已确实放入存储（直传完成 / 迁移落地）后再登记
  • 示例响应：
json
{ "code": 173013, "msg": "对象在存储中不存在", "data": null }

173014 INGEST_URL_INVALID ​

  • HTTP status：200
  • 含义：摄入 URL 非法或协议不支持
  • 典型触发条件：from-url 的 url 格式非法，或协议不是 http / https
  • 处理建议：提供格式合法的 http / https URL
  • 示例响应：
json
{ "code": 173014, "msg": "URL 非法或协议不支持", "data": null }

173015 INGEST_URL_BLOCKED ​

  • HTTP status：200
  • 含义：摄入 URL 指向受限地址
  • 典型触发条件：from-url 的目标解析到内网 / 回环 / 链路本地等受限地址，被安全策略拦截
  • 处理建议：仅提供可公开访问的外部 URL；内网资源请改走预签名直传或带外迁移后 register-object
  • 示例响应：
json
{ "code": 173015, "msg": "URL 指向受限地址", "data": null }

173016 INGEST_FETCH_FAILED ​

  • HTTP status：200
  • 含义：URL 拉取失败
  • 典型触发条件：from-url 拉取目标超时、连接被拒、返回非成功状态码或重定向次数过多
  • 处理建议：确认 URL 可达且稳定返回内容后重试；大文件 / 大小未知会转异步任务，可凭 GET /v1/ingest/task 查最终失败原因
  • 示例响应：
json
{ "code": 173016, "msg": "URL 拉取失败", "data": null }

173017 INGEST_SIZE_EXCEEDED ​

  • HTTP status：200
  • 含义：摄入内容超过大小上限
  • 典型触发条件：from-url 拉取的内容超过配置的大小上限
  • 处理建议：分拆内容或联系部署方调高上限
  • 示例响应：
json
{ "code": 173017, "msg": "摄入内容超过大小上限", "data": null }

分片上传会话 173018 ​

173018 UPLOAD_SESSION_NOT_FOUND ​

  • HTTP status：200
  • 含义：分片上传会话不存在
  • 典型触发条件：以一个查无对应（或已被清理）的 uploadId 调用上传分片 / 完成分片上传
  • 处理建议：重新 POST /v1/versions/initChunkedUpload 取得新的 uploadId，再续传 / 完成
  • 示例响应：
json
{ "code": 173018, "msg": "上传会话不存在", "data": null }