BaiduPCS-Go 文件数据 API 错误码详解从 error_code 对照表到源码级错误处理机制【免费下载链接】BaiduPCS-Goiikira/BaiduPCS-Go原版基础上集成了分享链接/秒传链接转存功能项目地址: https://gitcode.com/GitHub_Trending/ba/BaiduPCS-GoBaiduPCS-Go 通过调用百度 PCSPan Cloud StorageREST 文件 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 响应状态码通常不为 200Content-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上传时未指定ondupoverwrite/newcopy见 文件API列表 中上传单个文件一节或ondupnewcopy策略失效时的典型结果属于请求侧可修正错误。31066文件不存在403与 31202object not exists404一个偏向业务层鉴权视角、一个偏向对象存储层排障时可结合 URL 前缀rest/2.0/pcs/file 与对象存储网关区分。31079File md5 not found404调用秒传rapidupload时服务端没有对应 MD5 的记录文档明确提示请使用上传API上传整个文件——这正是 BaiduPCS-Go 秒传失败后降级走完整上传流程的判断依据。31218storage exceed limit403容量超出限额是转存他人分享文件到已满网盘时的直接阻断错误。401 110Access 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 )这个分类很关键错误码表里的 31021network error、31022can not access server属于服务端报告的网络类错误远端错误码而客户端本地发生的 TCP 超时、DNS 失败则归入ErrTypeNetError——两者的处理策略是否重试、重试上限可以分开实现。2.2 JSON 错误码的解析入口三个 API 族对应三个解析入口pcserror.go L55-L71DecodePCSJSONError解析文件数据 API即本文错误码表所属的响应错误载体为error_code/error_msg字段DecodePanJSONError解析网盘网页接口pan.baidu.com 侧响应错误载体为errno字段DecodeXPanJSONError解析 xpan 接口响应额外携带return_type。三者最终汇入HandleJSONParsepcserror.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/31215put 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/31217get 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 的通用排障决策表4xx 参数类31023、31024、31062、31063、31111–31114、31208请求自身有问题。先检查path是否合法文件API列表 规定路径长度 ≤1000、不得含\ ? | : *且首尾不能是.或空白字符、ondup是否指定、目录配额层级是否超过两级。这类错误重试无意义必须先修正。4xx 鉴权/权限类3、4、5、110、31041–31046、31064、31211凭证问题。Open API 场景刷新/重签 access_token登录态场景31045 user not exists 在 findPCSErr 中被改写为可能百度帐号登录状态过期请尝试重新登录需要用户重新执行登录。4xx 状态类31061、31066、31079、31202对象状态与请求预期不符。31061 检查是否漏设ondup31079 秒传未命中 MD5 时应按文档提示降级为完整上传这也是上传流程从 upload.go 秒传分支回退整文件上传的依据。5xx31001–31003、31021–31022、31025、31067–31083、31101–31103、31141、31209、31212–31217、31298–31299服务端故障。按服务器端错误客户端需要重试的原则做有限次退避重试若重试持续失败如 31021 network error、31212/31213 service unavailable则终止任务并向用户上报避免无限循环。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_msgHandleJSONParse按非 0 即远端错误归入ErrTypeRemoteErrorfindPCSErr 对 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考