企业官网建设流程全解析

BaiduPCS-Go 文件数据 API 错误码详解：从 error_code 对照表到源码级错误处理机制

【免费下载链接】BaiduPCS-Goiikira/BaiduPCS-Go原版基础上集成了分享链接/秒传链接转存功能项目地址: https://gitcode.com/GitHub_Trending/ba/BaiduPCS-Go

BaiduPCS-Go 通过调用百度 PCS（Pan Cloud Storage）REST 文件 API 实现文件的上传、下载、拷贝、删除、回收站与转存等操作，而每一次调用都可能以error_code形式返回错误。本文以仓库中的错误码文档 文件数据API错误码 为主体，完整收录官方错误码对照表，并结合 baidupcs/pcserror 包的源码实现，讲清楚每一类错误码的含义、触发场景，以及程序在解析响应、映射中文错误信息、决定"重试还是终止"时的完整处理链路，帮助你在自行调用 PCS 文件 API 或阅读该项目排障逻辑时做到码码可查、错错可断。

一、错误码体系总览：先看 HTTP 状态码，再看 error_code

根据 概述文档，百度开放云平台的 PCS 服务分为文件 API（上传、下载、拷贝、删除、搜索、断点续传、缩略图）与结构化数据 API（结构数据存储、查询、删除及同步）两部分，对应的错误码也各自成表——结构化数据 API 的错误码见 结构化数据API错误码（以 314xx 为主），而本文讨论的文件数据 API错误码则集中在 310xx 与 312xx 号段，另有少量通用号。

请求成功时，HTTP 状态码为 200 且error_code为 0，响应体中不包含error_msg；请求失败时，HTTP 响应状态码通常不为 200，Content-body 中的 JSON 数据以error_code给出错误码，并以error_msg字段提示错误信息。整体遵循客户端/服务器端二分原则：

• 客户端错误（4xx）：请求参数不对、权限不足、配额超出等，客户端需要先修正参数或凭证，再重新发起请求，盲目重试没有意义；
• 服务器端错误（5xx）：平台内部发生错误（数据库故障、后端存储错误、服务不可用等），客户端在参数正确的前提下适合做退避重试。

下面完整收录 docs/file_data_apis_error.md 中的官方错误码对照表：

| HTTP状态码 | 错误码 | 错误信息 | 备注 | | :- | -: | :- | :- | | 200 | 0 | no error | 没有错误 | | 400 | 3 | Unsupported open api | 不支持此接口 | | 403 | 4 | No permission to do this operation | 没有权限执行此操作 | | 403 | 5 | Unauthorized client IP address | IP未授权 | | 503 | 31001 | db query error | 数据库查询错误 | | 503 | 31002 | db connect error | 数据库连接错误 | | 503 | 31003 | db result set is empty | 数据库返回空结果 | | 503 | 31021 | network error | 网络错误 | | 503 | 31022 | can not access server | 暂时无法连接服务器 | | 400 | 31023 | param error | 输入参数错误 | | 400 | 31024 | app id is empty | app id为空 | | 503 | 31025 | bcs error | 后端存储错误 | | 403 | 31041 | bduss is invalid | 用户的cookie不是合法的百度cookie | | 403 | 31042 | user is not login | 用户未登陆 | | 403 | 31043 | user is not active | 用户未激活 | | 403 | 31044 | user is not authorized | 用户未授权 | | 403 | 31045 | user not exists | 用户不存在 | | 403 | 31046 | user already exists | 用户已经存在 | | 400 | 31061 | file already exists | 文件已经存在 | | 400 | 31062 | file name is invalid | 文件名非法 | | 400 | 31063 | file parent path does not exist | 文件父目录不存在 | | 403 | 31064 | file is not authorized | 无权访问此文件 | | 400 | 31065 | directory is full | 目录已满 | | 403 | 31066 | file does not exist | 文件不存在 | | 503 | 31067 | file deal failed | 文件处理出错 | | 503 | 31068 | file create failed | 文件创建失败 | | 503 | 31069 | file copy failed | 文件拷贝失败 | | 503 | 31070 | file delete failed | 文件删除失败 | | 503 | 31071 | get file meta failed | 不能读取文件元信息 | | 503 | 31072 | file move failed | 文件移动失败 | | 503 | 31073 | file rename failed | 文件重命名失败 | | 503 | 31081 | superfile create failed | superfile创建失败 | | 503 | 31082 | superfile block list is empty | superfile 块列表为空 | | 503 | 31083 | superfile update failed | superfile 更新失败 | | 503 | 31101 | tag internal error | tag系统内部错误 | | 503 | 31102 | tag param error | tag参数错误 | | 503 | 31103 | tag database error | tag系统错误 | | 403 | 31110 | access denied to set quota | 未授权设置此目录配额 | | 400 | 31111 | quota only sopport 2 level directories | 配额管理只支持两级目录 | | 400 | 31112 | exceed quota | 超出配额 | | 403 | 31113 | the quota is bigger than one of its parent directories | 配额不能超出目录祖先的配额 | | 403 | 31114 | the quota is smaller than one of its sub directories | 配额不能比子目录配额小 | | 503 | 31141 | thumbnail failed, internal error | 请求缩略图服务失败 | | 401 | 110 | Access token invalid or no longer valid | Access Token不正确或者已经过期 | | 400 | 31201 | signature error | 签名错误 | | 400 | 31203 | acl put error | 设置acl失败 | | 400 | 31204 | acl query error | 请求acl验证失败 | | 400 | 31205 | acl get error | 获取acl失败 | | 404 | 31079 | File md5 not found, you should use upload API to upload the whole file. | 未找到文件MD5，请使用上传API上传整个文件 | | 404 | 31202 | object not exists | 文件不存在 | | 404 | 31206 | acl get error | acl不存在 | | 400 | 31207 | bucket already exists | bucket已存在 | | 400 | 31208 | bad request | 用户请求错误 | | 500 | 31209 | baidubs internal error | 服务器错误 | | 501 | 31210 | not implement | 服务器不支持 | | 403 | 31211 | access denied | 禁止访问 | | 503 | 31212 | service unavailable | 服务不可用 | | 503 | 31213 | service unavailable | 重试出错 | | 503 | 31214 | put object data error | 上传文件data失败 | | 503 | 31215 | put object meta error | 上传文件meta失败 | | 503 | 31216 | get object data error | 下载文件data失败 | | 503 | 31217 | get object meta error | 下载文件meta失败 | | 403 | 31218 | storage exceed limit | 容量超出限额 | | 403 | 31219 | request exceed limit | 请求数超出限额 | | 403 | 31220 | transfer exceed limit | 流量超出限额 | | 500 | 31298 | the value of KEY[VALUE] in pcs response headers is invalid | 服务器返回值KEY非法 | | 500 | 31299 | no KEY in pcs response headers | 服务器返回值KEY不存在 |

按号段理解错误码的归属

从号段划分可以推断每类错误的责任边界，这对排障定位"该改请求还是该等恢复"至关重要：

| 号段/类别 | 典型错误码 | 责任边界与处理建议 | | :- | :- | :- | | 通用码 | 0、3、4、5、110 | 协议层与鉴权层：不支持的接口、无权限、IP 未授权、Access Token 过期 | | 31001–31025 | 31001–31003、31021–31025 | 平台基础服务：数据库、网络、参数、后端存储，多为 5xx 服务端故障 | | 31041–31046 | 31041–31046 | 用户态/登录态：bduss 非法、未登录、未激活、用户不存在等，需重新登录 | | 31061–31073 | 31061–31073 | 文件操作核心域：同名冲突、路径不存在、文件不存在、拷贝/删除/移动失败 | | 31079 / 31202 | 31079、31202 | 404 类：秒传时未命中 MD5、对象不存在 | | 31081–31083 | 31081–31083 | 分片（superfile）上传链路：创建、块列表为空、更新失败 | | 31101–31103 | 31101–31103 | tag 系统内部错误 | | 31110–31114 | 31110–31114 | 目录配额管理：仅支持两级目录、配额层级约束 | | 31141 | 31141 | 缩略图服务失败 | | 31201–31220 | 31201–31220 | 对象存储层：签名、ACL、bucket、对象 data/meta 读写、存储/请求/流量限额 | | 31298–31299 | 31298、31299 | 服务端响应头 KEY 非法或缺失 |

几个高频码值得单独强调：

• 31061（文件已存在，400）：上传时未指定ondup（overwrite/newcopy，见 文件API列表 中"上传单个文件"一节）或ondup=newcopy策略失效时的典型结果，属于请求侧可修正错误。
• 31066（文件不存在，403）与 31202（object not exists，404）：一个偏向业务层鉴权视角、一个偏向对象存储层，排障时可结合 URL 前缀（rest/2.0/pcs/file 与对象存储网关）区分。
• 31079（File md5 not found，404）：调用秒传（rapidupload）时服务端没有对应 MD5 的记录，文档明确提示"请使用上传API上传整个文件"——这正是 BaiduPCS-Go 秒传失败后降级走完整上传流程的判断依据。
• 31218（storage exceed limit，403）：容量超出限额，是转存他人分享文件到已满网盘时的直接阻断错误。
• 401 + 110（Access token 无效/过期）：Open API 模式下 access_token 失效，与 OpenAPI 无关的登录态问题（31041–31046）不同。

二、源码印证：BaiduPCS-Go 如何解析这些错误码

上述对照表是"服务端视角"；BaiduPCS-Go 在 baidupcs/pcserror 包中实现了完整的"客户端视角"错误处理框架，将error_code/error_msg的 JSON 响应解析为可比较、可展示、可决策的 Goerror。

2.1 统一的 Error 接口与六类错误分类

pcserror.go 定义了统一的Error接口（内嵌标准error接口），要求实现者提供 JSON/网络错误注入、远端错误标记以及操作名、错误类型、远端错误码与消息的读取方法。与之配套的是 ErrType 枚举，把一次操作的所有失败来源划分为六类：

const ( // ErrorTypeNoError 无错误 ErrorTypeNoError ErrType = iota // ErrTypeInternalError 内部错误 ErrTypeInternalError // ErrTypeRemoteError 远端服务器返回错误 ErrTypeRemoteError // ErrTypeNetError 网络错误 ErrTypeNetError // ErrTypeJSONParseError json 数据解析失败 ErrTypeJSONParseError // ErrTypeOthers 其他错误 ErrTypeOthers )

这个分类很关键：错误码表里的 31021（network error）、31022（can not access server）属于服务端报告的网络类错误（远端错误码），而客户端本地发生的 TCP 超时、DNS 失败则归入ErrTypeNetError——两者的处理策略（是否重试、重试上限）可以分开实现。

2.2 JSON 错误码的解析入口

三个 API 族对应三个解析入口（pcserror.go L55-L71）：

• DecodePCSJSONError：解析文件数据 API（即本文错误码表所属）的响应，错误载体为error_code/error_msg字段；
• DecodePanJSONError：解析网盘网页接口（pan.baidu.com 侧）响应，错误载体为errno字段；
• DecodeXPanJSONError：解析 xpan 接口响应，额外携带return_type。

三者最终汇入HandleJSONParse（pcserror.go L73-L95），核心逻辑是：

// HandleJSONParse 处理解析json func HandleJSONParse(op string, data io.Reader, info interface{}) (pcsError Error) { // ... if err != nil { errInfo.SetJSONError(err) // JSON 解析失败 -> ErrTypeJSONParseError return errInfo } // 设置出错类型为远程错误 if errInfo.GetRemoteErrCode() != 0 { errInfo.SetRemoteError() // error_code 非 0 -> ErrTypeRemoteError return errInfo } return nil }

也就是说：只要error_code不为 0，就被标记为ErrTypeRemoteError（远端服务器返回错误）；解析不出 JSON 则标记为ErrTypeJSONParseError；而 HTTP 传输阶段本身失败（连接重置、超时）不会走到这里，由上层直接调用SetNetError归入ErrTypeNetError。这与错误码表中"客户端错误改参数、服务器端错误可重试"的分层完全吻合。

PCSErrInfo结构体（pcserrorinfo.go L9-L16）用json:"error_code"与json:"error_msg"标签直接映射响应 JSON 中的两个字段，Operation字段记录"正在进行的操作"名称（如upload、remove、mkdir），用于拼装最终错误文本。

2.3 面向用户的错误信息：findPCSErr 的关键码改写

Error()方法（pcserrorinfo.go L69-L100）按ErrType分支格式化输出；远端错误分支的格式为：

{操作名}: 遇到错误, 远端服务器返回错误, 代码: {error_code}, 消息: {error_msg}

其中的error_msg并非原样透传，而是先经过 findPCSErr 做"关键错误码改写"，当前源码显式处理了错误码表中的 4 个高频码：

// findPCSErr 检查 PCS 错误, 查找已知错误 func findPCSErr(errCode int, errMsg string) (int, string) { switch errCode { case 0: return errCode, "" case 31045: // user not exists return errCode, "操作失败, 可能百度帐号登录状态过期, 请尝试重新登录, 消息: " + errMsg case 31061: // file already exists return errCode, "文件已存在" case 31066: // file does not exist return errCode, "文件或目录不存在" case 31079: // file md5 not found, you should use upload api to upload the whole file. return errCode, "秒传文件失败" } return errCode, errMsg }

这 4 个码正是文件操作场景中出现概率最高、且需要用户可理解提示的码：31045（用户不存在/登录态失效）、31061（文件已存在）、31066（文件或目录不存在）、31079（秒传未命中 MD5）。对于不在改写表中的其余错误码（如 31069 拷贝失败、31218 容量超限），则原样透传服务端error_msg，保证信息不失真。

2.4 各操作对错误解析的调用链

文件数据 API 的每个操作函数在执行后都会调用DecodePCSJSONError解析响应，operation 参数即操作名，源码中的实际调用点包括：

| 操作 | 源码位置 | 对应错误码表的典型关注码 | | :- | :- | :- | | 单文件上传/秒传 | upload.go L167 | 31061、31079、31214/31215（put object data/meta error） | | 创建 superfile（分片上传初始化） | upload.go L215 | 31081–31083 | | 拷贝/移动/重命名 | cp_mv_rename.go L34 | 31066、31069、31072、31073、31061 | | 删除/新建目录 | rm_mkdir.go L17-L36 | 31066、31070、31068、31063 | | 云下载 | cloud_dl.go L261 | 31216/31217（get object data/meta error） | | 请求前置处理 | prepare.go L41 | 31021/31022（网络类 503） |

此外，DecodePanJSONError被用于回收站（recycle.go L95）与分享/取消分享（share.go L114）等走网盘网页接口的操作。从源码结构看，文件数据 API 的操作统一以 PCS 错误码（本文表格）为契约，而回收站与分享链路走的是另一套errno体系，其对照实现在 FindPanErr（覆盖-19需验证码、-30文件已存在、-31文件保存失败、132安全验证等网盘侧错误），两套体系互不混用。

三、实战排障：按"码段 → 处理策略"决策

结合错误码表与源码处理框架，可以沉淀出一套文件数据 API 的通用排障决策表：

1. 4xx + 参数类（31023、31024、31062、31063、31111–31114、31208）：请求自身有问题。先检查path是否合法（文件API列表 规定路径长度 ≤1000、不得含\ ? | " > < : *，且首尾不能是.或空白字符）、ondup是否指定、目录配额层级是否超过两级。这类错误重试无意义，必须先修正。
2. 4xx + 鉴权/权限类（3、4、5、110、31041–31046、31064、31211）：凭证问题。Open API 场景刷新/重签 access_token；登录态场景（31045 "user not exists" 在 findPCSErr 中被改写为"可能百度帐号登录状态过期，请尝试重新登录"）需要用户重新执行登录。
3. 4xx + 状态类（31061、31066、31079、31202）：对象状态与请求预期不符。31061 检查是否漏设ondup；31079 秒传未命中 MD5 时应按文档提示降级为完整上传（这也是上传流程从 upload.go 秒传分支回退整文件上传的依据）。
4. 5xx（31001–31003、31021–31022、31025、31067–31083、31101–31103、31141、31209、31212–31217、31298–31299）：服务端故障。按"服务器端错误：客户端需要重试"的原则做有限次退避重试；若重试持续失败（如 31021 network error、31212/31213 service unavailable）则终止任务并向用户上报，避免无限循环。
5. 403 + 限额类（31218、31219、31220、31112）：容量、请求数或流量超出配额，属于账户级约束，重试无效，需要用户清理空间或等待限额窗口恢复。

对于自行调用 PCS 文件 API 的开发者，上述分类同样适用：先读 HTTP 状态码定"客户端改错还是服务端重试"，再按error_code精确匹配到上表定位根因——这正是 BaiduPCS-Go 在 pcserror 包 中以ErrType分层、以findPCSErr改写关键码所体现的工程实践。

四、小结

• docs/file_data_apis_error.md 给出了文件数据 API 的完整错误码契约：200/0 表示成功，4xx 需修正请求，5xx 可重试；错误码集中在 310xx（文件域）与 312xx（对象存储域）号段，另有 0/3/4/5/110 等通用码。
• BaiduPCS-Go 以 baidupcs/pcserror 包将其落地为 Go 错误体系：DecodePCSJSONError解析error_code/error_msg，HandleJSONParse按"非 0 即远端错误"归入ErrTypeRemoteError，findPCSErr 对 31045/31061/31066/31079 四个高频码给出面向用户的中文改写，其余码透传服务端消息。
• 上传、云下载、拷贝移动、删除建目录等文件 API 操作均在 baidupcs 各操作函数中按此契约解析响应；而回收站、分享等网页侧接口使用errno体系（FindPanErr），结构化数据 API 则使用 314xx 号段（见 structured_data_apis_error.md），三者不可混用。

【免费下载链接】BaiduPCS-Goiikira/BaiduPCS-Go原版基础上集成了分享链接/秒传链接转存功能项目地址: https://gitcode.com/GitHub_Trending/ba/BaiduPCS-Go