Skip to main content

错误码

RAG 数据集 API 错误响应与处理建议

所有错误响应使用统一结构： 
{
  "code": "InvalidParameter",
  "status_code": 400,
  "message": "Required parameter missing or invalid.",
  "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

HTTP 状态码

状态码含义处理建议
400请求参数错误校对参数，注意必填项与枚举值
401鉴权失败检查 API Key 是否有效、是否过期
403无权限申请 AliyunBailianDataFullAccess 或加入业务空间
404资源不存在校对 fileId、categoryId、connectorId
429限流退避重试
500服务内部错误重试
503服务不可用退避重试

业务错误码

codeHTTP说明
InvalidParameter400参数缺失或格式错误
InvalidApiKey401API Key 缺失或无效
NotFound404资源（数据集/类目/文件）不存在
QuotaExceeded429超出租户配额
RateLimited429接口限流
InternalError500服务内部异常
OSSAccessDenied403OSS SLR 授权缺失，见 OSS 批量导入

常见问题

现象原因解决方案
maxResults 不生效参数名拼错正确参数名为 maxResult（单数），见 listCategory
文件上传后 addFile 报错租约失效租约有时效重新调用 applyFileUploadLease 获取新租约
OSS 批量导入返回权限错误未配置 SLR在 RAM 控制台创建 AliyunServiceRoleForBailian
sizeBytes 校验失败传了数字必须以字符串格式传入（如 "1048576"）

重试策略

错误类型是否重试间隔
4xx（限流除外）否—
429 限流是1s/2s/4s 指数退避
5xx是1s/2s/4s，最多 3 次

排错

每个响应都带 requestId，可用于快速定位日志。
排查完毕后，从新增数据集开始你的第一次调用。