Connector API 错误响应与处理建议
所有错误响应使用统一结构：
每个响应都带
HTTP 状态码
| 状态码 | 含义 | 处理建议 |
|---|---|---|
| 400 | 请求参数错误 | 校对参数，注意必填项与枚举值 |
| 401 | 鉴权失败 | 检查 API Key 是否有效、是否过期 |
| 403 | 无权限 | 申请 AliyunBailianDataFullAccess 或加入业务空间 |
| 404 | 资源不存在 | 校对 fileId、categoryId、connectorId |
| 429 | 限流 | 退避重试 |
| 500 | 服务内部错误 | 重试，持续失败联系支持 |
| 503 | 服务不可用 | 退避重试 |
业务错误码
| code | HTTP | 说明 |
|---|---|---|
InvalidParameter | 400 | 参数缺失或格式错误 |
InvalidApiKey | 401 | API Key 缺失或无效 |
NotFound | 404 | 资源（连接器/类目/文件）不存在 |
QuotaExceeded | 429 | 超出租户配额 |
RateLimited | 429 | 接口限流 |
InternalError | 500 | 服务内部异常 |
OSSAccessDenied | 403 | OSS SLR 授权缺失，见 OSS 批量导入 |
常见问题
| 现象 | 原因 | 解决方案 |
|---|---|---|
maxResults 不生效 | 参数名拼错 | 正确参数名为 maxResult（单数），见 listCategory |
文件上传后 addFile 报错租约失效 | 租约有时效 | 重新调用 applyFileUploadLease 获取新租约 |
| OSS 批量导入返回权限错误 | 未配置 SLR | 在 RAM 控制台创建 AliyunServiceRoleForBailian |
sizeBytes 校验失败 | 传了数字 | 必须以字符串格式传入（如 "1048576"） |
重试策略
| 错误类型 | 是否重试 | 间隔 |
|---|---|---|
| 4xx（限流除外） | 否 | — |
| 429 限流 | 是 | 1s/2s/4s 指数退避 |
| 5xx | 是 | 1s/2s/4s，最多 3 次 |
排错
每个响应都带 requestId。联系支持时附上该 ID，可快速定位日志。