当用户访问OSS出现错误时,OSS会返回给用户相应的错误码和错误信息,便于用户定位问题,并做出适当的处理。

OSS的错误响应格式

当用户访问OSS出错时,OSS会返回给用户一个合适的3xx,4xx或者5xx的HTTP状态码;以及一个application/xml格式的消息体。

错误响应的消息体例子:

<?xml version="1.0" ?>
<Error xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
    <Code>
        AccessDenied
    </Code>
    <Message>
        Query-string authentication requires the Signature, Expires and OSSAccessKeyId parameters
    </Message>
    <RequestId>
        1D842BC5425544BB
    </RequestId>
    <HostId>
        oss-cn-hangzhou.aliyuncs.com
    </HostId>
</Error>

所有错误的消息体中都包括以下几个元素:

  • Code:OSS返回给用户的错误码。
  • Message:OSS给出的详细错误信息。
  • RequestId:用于唯一标识该次请求的UUID;当你无法解决问题时,可以凭这个RequestId来请求OSS开发工程师的帮助。
  • HostId:用于标识访问的OSS集群,与用户请求时使用的Host一致。

其他特殊的错误信息元素请参照每个请求的具体介绍。

OSS的错误码

OSS的错误码列表如下:

错误码 描述 HTTP状态码 说明
AccessDenied 拒绝访问 403 原因及排除请参看权限问题及排查
BucketAlreadyExists Bucket已经存在 409 CreateBucket指定的BucketName已经使用,请选择新的BucketName
BucketNotEmpty Bucket不为空 409 DeleteBucket前请先删除文件和未完成的分片上传任务
CallbackFailed 上传回调失败 203 原因及排除请参看上传回调错误及排除
EntityTooLarge 实体过大 400 Post请求消息长度超过 5GB,原因及排除请参看PostObject错误及排查
EntityTooSmall 实体过小 400 Post请求消息长度太短,排除请参看PostObject错误及排查
FieldItemTooLong Post请求中表单域过大 400 除了file的表单域大小不要超过4KB,排除请参看PostObject错误及排查
FilePartInterity 文件Part已改变 400 读分片数据时发现数据与校验和不符
FilePartNotExist 文件Part不存在 400 CompleteMultipartUpload提交的分片没有上传
FilePartStale 文件Part过时 400 读分片数据时发现数据与长度不符
IncorrectNumberOfFilesInPOSTRequest Post请求中文件个数非法 400 Post请求表单域中只能有一个file域,排除请参看PostObject错误及排查
InvalidArgument 参数格式错误 400 参数格式不符合要求,请对照相应API
InvalidAccessKeyId AccessKeyId不存在 403 AccessKeyId无效或过期,排除请参看403错误及排查
InvalidBucketName 无效的Bucket名字 400 Bucket命名规则请参看开发人员指南
InvalidDigest 无效的摘要 400 指定的MD5校验值与文件不符,MD5的计算方法请参见PutObject
InvalidEncryptionAlgorithmError 指定的熵编码加密算法错误 400 目前只支持AES256加密算法,详见PutObject
InvalidObjectName 无效的Object名字 400 ObjectName命名规则请参看开发人员指南
InvalidPart 无效的Part 400 CompleteMultipartUpload提交的Part无效,PartNumberETag错误
InvalidPartOrder 无效的part顺序 400 CompleteMultipartUpload提交的Part需按照PartNumber升序排列
InvalidPolicyDocument 无效的Policy文档 400 Post请求中Policy无效,排除请参看PostObject错误及排查
InvalidTargetBucketForLogging Logging操作中有无效的目标bucket 400 存放Logging的目标bucket不存在,请更换
InternalError OSS内部发生错误 500 请重试
MalformedXML XML格式非法 400 请求中XML非法,请根据具体请求排除DeleteObjectsCompleteMultipartUploadPutBucketLoggingPutBucketWebsitePutBucketLifecyclePutBucketRefererPutBucketCORS
MalformedPOSTRequest Post请求的body格式非法 400 表单域格式非法,排除请参看PostObject错误及排查
MaxPOSTPreDataLengthExceededError Post请求上传文件内容之外的body过大 400 除了file的表单域大小不要超过4KB,排除请参看PostObject错误及排查
MethodNotAllowed 不支持的方法 405 以OSS不支持的操作来访问资源
MissingArgument 缺少参数 411 请参看具体的API对照解决
MissingContentLength 缺少内容长度 411 消息即非chunked encoding又没有携带Content-Length
NoSuchBucket Bucket不存在 404
NoSuchKey Object不存在 404
NoSuchUpload Multipart Upload ID不存在 404 没有初始化分片上传或者初始化的分片上传过期
NotImplemented 无法处理的方法 400 OSS不支持的操作
ObjectNotAppendable 不是可追加文件 409 OSS有三类文件normalappendablemultipart,只有appendable类型的文件才能执行AppendObject
PositionNotEqualToLength Append的位置和文件长度不相等 409 详见AppendObject
PreconditionFailed 预处理错误 412 下载条件不符合,详见GetObject
RequestTimeTooSkewed 发起请求的时间和服务器时间超出15分钟 403 排除请参看403错误及排查
RequestTimeout 请求超时 400 请重试
RequestIsNotMultiPartContent Post请求content-type非法 400 排除请参看PostObject错误及排查
DownloadTrafficRateLimitExceeded 下载流量超过限制 503

默认上限是 5Gbps,包括内外网,有调整需求请提交工单

UploadTrafficRateLimitExceeded 上传流量超过限制 503

默认上限是 5Gbps,包括内外网,有调整需求请提交工单

SignatureDoesNotMatch 签名错误 403 排除请参看Header中签名URL中签名
TooManyBuckets Bucket数目超过限制 400

默认上限是 10,有调整需求请提交工单

SDK/Tool常见错误及排除

OSS不支持的操作

如果试图以OSS不支持的操作来访问某个资源,返回405 Method Not Allowed错误。

错误请求示例:
ABC /1.txt HTTP/1.1
Host: bucketname.oss-cn-shanghai.aliyuncs.com
Date: Thu, 11 Aug 2016 03:53:40 GMT
Authorization: signatureValue
返回示例:
HTTP/1.1 405 Method Not Allowed
Server: AliyunOSS
Date: Thu, 11 Aug 2016 03:53:44 GMT
Content-Type: application/xml
Content-Length: 338
Connection: keep-alive
x-oss-request-id: 57ABF6C8BC4D25D86CBA5ADE
Allow: GET DELETE HEAD PUT POST OPTIONS
<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>MethodNotAllowed</Code>
  <Message>The specified method is not allowed against this resource.</Message>
  <RequestId>57ABF6C8BC4D25D86CBA5ADE</RequestId>
  <HostId>bucketname.oss-cn-shanghai.aliyuncs.com</HostId>
  <Method>abc</Method>
  <ResourceType>Bucket</ResourceType>
</Error>
说明
如果访问的资源是 /bucket/, ResourceType应该是bucket,如果访问的资源是 /bucket/object,ResourceType应该是object。

OSS操作支持但参数不支持的操作

如果在OSS合法的操作中,添加了OSS不支持的参数(例如在PUT的时候,加入If-Modified-Since参数),OSS会返回400 Bad Request错误

错误请求示例:
PUT /abc.zip HTTP/1.1
Host: bucketname.oss-cn-shanghai.aliyuncs.com
Accept: */*
Date: Thu, 11 Aug 2016 01:44:50 GMT
If-Modified-Since: Thu, 11 Aug 2016 01:43:51 GMT
Content-Length: 363
返回示例:
HTTP/1.1 400 Bad Request
Server: AliyunOSS
Date: Thu, 11 Aug 2016 01:44:54 GMT
Content-Type: application/xml
Content-Length: 322
Connection: keep-alive
x-oss-request-id: 57ABD896CCB80C366955187E
x-oss-server-time: 0
<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>NotImplemented</Code>
  <Message>A header you provided implies functionality that is not implemented.</Message>
  <RequestId>57ABD896CCB80C366955187E</RequestId>
  <HostId>bucketname.oss-cn-shanghai.aliyuncs.com</HostId>
  <Header>If-Modified-Since</Header>
</Error>