如何实现OSS错误响应？

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

OSS的错误响应格式


当用户访问OSS出错时，OSS会返回给用户一个合适的3xx，4xx或者5xx的HTTP状态码；以及一个application/xml格式的消息体。
[backcolor=transparent]错误响应的消息体例子： <?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请求消息长度超过 [backcolor=transparent]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无效，PartNumber或ETag错误
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非法，请根据具体请求排除DeleteObjects、CompleteMultipartUpload、PutBucketLogging、PutBucketWebsite、PutBucketLifecycle、PutBucketReferer、PutBucketCORS
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有三类文件normal、appendable、multipart，只有appendable类型的文件才能执行AppendObject
PositionNotEqualToLength	Append的位置和文件长度不相等	409	详见AppendObject
PreconditionFailed	预处理错误	412	下载条件不符合，详见GetObject
RequestTimeTooSkewed	发起请求的时间和服务器时间超出15分钟	403	排除请参看403错误及排查
RequestTimeout	请求超时	400	请重试
RequestIsNotMultiPartContent	Post请求content-type非法	400	排除请参看PostObject错误及排查
DownloadTrafficRateLimitExceeded	下载流量超过限制	503	默认上限是 [backcolor=transparent]5Gbps，包括内外网，有调整需求请提交工单
UploadTrafficRateLimitExceeded	上传流量超过限制	503	默认上限是 [backcolor=transparent]5Gbps，包括内外网，有调整需求请提交工单
SignatureDoesNotMatch	签名错误	403	排除请参看Header中签名、URL中签名
TooManyBuckets	Bucket数目超过限制	400	默认上限是 [backcolor=transparent]10，有调整需求请提交工单

OSS常见错误及排除

• 上传回调错误及排除
• 403错误及排查
• PostObject错误及排查
• 权限问题及排查
• 跨域资源共享CORS错误及排除
• 防盗链Referer配置及错误排除
• STS常见问题及排查
• 图片处理

SDK/Tool常见错误及排除

• Java SDK
• Python SDK
• C SDK
• ossfs
• ossimport
• ossftp
• ossutil

OSS不支持的操作


如果试图以OSS不支持的操作来访问某个资源，返回405 Method Not Allowed错误。
[backcolor=transparent]错误请求示例： ABC /1.txt HTTP/1.1
Host: bucketname.oss-cn-shanghai.aliyuncs.com
Date: Thu, 11 Aug 2016 03:53:40 GMT
Authorization: signatureValue

[backcolor=transparent]返回示例： 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错误
[backcolor=transparent]错误请求示例： 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

[backcolor=transparent]返回示例： 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>