通过状态码和OSS报错码排查问题

概述

当用户访问OSS出现错误时，OSS会返回一个3xx、4xx或者5xx的HTTP状态码以及一个application/xml格式的消息体，便于用户定位问题并解决问题。基于此，您可以通过OSS返回的错误信息在本文匹配解决方案。

说明：关于如何解读OSS返回的消息体，请参见错误响应消息体。

详细信息

常见错误码汇总

如下为OSS返回的常见错误码，更多OSS错误码信息，请参见OSS错误中心。

说明：

  • 您可以通过浏览器的查找功能在本文快速匹配HTTP状态码或者OSS错误码。
  • 如果您受限于服务端的日志存储空间而丢失了部分日志，建议您使用OSS的日志存储服务，记录Bucket上所有访问日志，详情请参见设置日志存储。
HTTP状态码 OSS错误码 错误消息 问题原因 解决方案

203

 CallbackFailed
  • Get image info failed
  • Too many callback requests
  • Cost too long time
 回调参数设置错误或参数格式错误，如ArgumentValue之间的回调参数，不是有效JSON格式等导致上传回调失败。 请参见上传回调错误及排查。
400 InvalidBucketName The specified bucket is not valid Bucket命名不符合规范 了解Bucket命名规范并检查Bucket名称。
InvalidObjectName 无效的Object名字 Object命名不符合规范 了解Object命名规范并检查Object名称。
TooManyBuckets Bucket数目超过限制 同一阿里云账号在同一地域内创建的Bucket数量不能超过30个 如需调整Bucket数量上限，请提交工单。
RequestIsNotMultiPartContent Post请求的Content-Type非法 Post操作提交的表单编码不是multipart/form-data类型 Post操作提交的表单编码必须为multipart/form-data类型，即Header中Content-Type为multipart/form-data;boundary=xxxxxx 这样的形式，boundary为边界字符串。详情可参见PostObject。
RequestTimeout 请求超时 因网络环境或网络配置等引起的网络超时 请参见网络超时处理进行排查。
NotImplemented 无法处理 封装API时传递了错误或者不支持的参数 请参见API概览中相应的API，填写正确的参数格式。
InvalidArgument 参数格式错误 参数格式不符合要求
MaxPOSTPreDataLengthExceededError Post请求上传文件内容之外的body过大 通过Post方法上传的文件大于5 GB，只有file的表单域大小允许超过4 KB。 请参见PostObject错误及排查。
FieldItemTooLong Post请求中表单域过大
MalformedPOSTRequest Post请求的body格式非法 表单域格式非法
InvalidPolicyDocument 无效的Policy文档 Post请求中的Policy格式不正确
IncorrectNumberOfFilesInPOSTRequest Post请求中文件个数非法 Post请求表单域中只能有一个file域
EntityTooSmall 实体过小 采用Post方法上传文件时，通过Post Policy设置表单域的合法值。例如content-length-range用于指定上传Object的允许大小（最小值和最大值）。 该condition支持contion-length-range匹配方式。 当过小或者过大时，则报相应错误。
EntityTooLarge 实体过大
MalformedXML XML格式非法 请求中的XML格式非法

请根据以下具体请求进行排除：
InvalidTargetBucketForLogging Logging操作中有无效的目标Bucket 存放Logging的目标Bucket无效 请更换有效的目标Bucket。
InvalidPart 无效的Part PartNumber或ETag错误导致CompleteMultipartUpload提交的Part无效 请参见CompleteMultipartUpload进行排查。
FilePartNotExist 文件Part不存在 CompleteMultipartUpload提交的分片没有上传
InvalidPartOrder 无效的Part顺序 CompleteMultipartUpload提交的Part顺序无效 请按照PartNumber升序排列，详情请参见CompleteMultipartUpload。
InvalidEncryptionAlgorithmError 指定的熵编码加密算法错误 指定x-oss-server-side-encryption的值无效，有效值为AES 256或KMS。 请参见PutObject进行排查。
InvalidDigest 无效的摘要 如果用户上传了Content-MD5请求头，OSS会计算body的Content-MD5并检查一致性。如果不一致，将返回InvalidDigest错误码。
InvalidTargetType 符号链接指向的目标Object类型无效 Object类型为软链接，且软链接指向的目标Object类型仍为软链接。 符号链接指向的目标Object不应该为软连接。
403 AccessDenied 拒绝访问 无指定操作的权限 请参见OSS权限相关的错误和排查方法。
InvalidAccessKeyId 无效的AK 可能是AccessKeyID禁用或不存在
SignatureDoesNotMatch 签名不符 签名不匹配
RequestTimeTooSkewed 请求时间偏差 发送请求的时间与OSS收到请求的时间间隔超出了15分钟，OSS从安全考虑认为该请求是无效的，返回报错。 请参见OSS403错误码的排查方法。
ImageDamage 图片损坏 图片文件有部分信息丢失或损坏，导致无法正常识别或处理。
UserDisable 用户被禁用 账号欠费或者由于安全原因账号被禁用。
AccessForbidden 禁止访问 没有配置CORS或CORS配置错误。 请参见OSS设置跨域访问。
InvalidObjectState 无效的Object状态 下载归档类型Object时，以下两种情况会导致报错无效的Object状态：
  • 没有提交RestoreObject请求或者上一次提交RestoreObject已经超时。
  • 已经提交RestoreObject请求，但数据的RestoreObject操作还没有完成。
 请参见RestoreObject进行排查。
404 SymlinkTargetNotExist Object类型为软链接，且软链接指向的目标Object不存在

不同场景对应的问题原因不同，具体如下：

  • 客户端显示上传成功，但下载提示404。
    • Object或Bucket名称拼写错误。
    • 上传成功后未收到OSS返回的requestId，即实际未上传成功。
    • 触发生命周期管理规则，Object被删除。
    • 分片上传或者断点续传时，部分分片上传成功，但最终未完成上传。
  • 文件之前一直存在，访问突然提示404。
    • Object被其他具有合法权限的用户通过OSS控制台、OSS客户端或API等方式删除了。
    • 目标Bucket与其他Bucket存在跨区域复制关系，其他Bucket中执行了删除操作，同步到目标Bucket中，所以文件也被删除了。

请参考以下步骤进行排查：

  1. 确保请求的Bucket名称是正确的。
  2. 确保请求的Object名称是正确的。如果是软连接，则确保软连接指向的Object是存在的。
  3. 检查OSS设置的生命周期规则，确认Object未触发删除规则。详情请参见设置生命周期管理规则。
  4. 确认请求的Object资源未被其他具有合法权限的用户删除了。
  5. 检查Bucket未与其他Bucket存在跨区域的复制关系。如果存在该关系，检查源Bucket中是否存在您请求的Object资源。
  6. 如果是上传Object资源后访问404，确认上传后收到返回的requestId。如果是分片上传或断点续传，确认最终以complete合并分片后返回的HTTP 200状态码以及requestId为准。详情请参见InitiateMultipartUpload。

为了后续通过日志快速定位404问题，建议您开启OSS的日志存储功能。详情请参见设置日志存储。
NoSuchBucket 当请求一个不存在的Bucket时会报此类错误
NoSuchKey 当请求一个不存在的Object时会报此类错误
NoSuchUpload MultipartUpload ID不存在，没有初始化分片上传或者初始化的分片上传过期。
405 MethodNotAllowed 不支持的方法 当操作行为不支持的话，会报此类错误。 查询OSS的API文档查看支持的操作。
409 BucketAlreadyExists Bucket已存在 指定的Bucket名称不唯一，与其他已经存在的Bucket名称重复。 请使用新的Bucket名称创建Bucket，Bucket命名规则请参见命名规则。
BucketNotEmpty Bucket不为空 要删除的Bucket中有未删除的Object或未完成的分片上传任务。为了防止误删除的发生，OSS不允许删除一个非空的Bucket。 请清空Bucket后再次尝试删除。详情请参见删除OSS中的Bucket时提示“Bucket不为空”。
ObjectNotAppendable 不是可追加文件 OSS有三种文件类型，分别为normal、appendable、multipart。只有appendable类型的文件才能执行AppendObject操作。 检查目标Object类型，确认是否为appendable类型。
PositionNotEqualToLength Append的位置和文件长度不相等
  • position的值和当前Object的长度不一致
  • position值为0时，如果没有同名Appendable Object，或者同名Appendable Object长度为0，该请求成功；其他情况均视为position和Object长度不匹配的情形，返回此错误码。
 您可以通过响应头x-oss-next-append-position得到下一次position，并再次进行请求。但由于并发的关系，即使把position的值设为了x-oss-next-append-position，该请求依然可能因为PositionNotEqualToLength而失败。
411 MissingContentLength 缺少内容长度 请求头没有采用chunked encoding编码方式，且没有Content-Length参数。 请采用chunked encoding编码方式并设置Content-Length参数。
412 PreconditionFailed 预处理错误
  • 指定了If-Unmodified-Since，但指定的时间早于Object实际修改时间。
  • 指定了If-Match，但源Object的ETag值和您提供的ETag不相等。
 请参见GetObject进行排查。
503 DownloadTrafficRateLimitExceeded 下载流量超过限制 内外网默认下载流量上限为5Gbit/s。有调整需求请提交工单。
UploadTrafficRateLimitExceeded 上传流量超过限制
MetaOperationQpsLimitExceeded 超出默认设置的QPS阈值

OSS针对以下管控类API进行QPS限制：

  • Service的操作：GetService (ListBuckets)
  • Bucket的操作，如PutBucket、GetBucketLifecycle等。
  • 跨域资源共享的操作，如PutBucketCORS、GetBucketCORS等。
  • LiveChannel的操作，如PutLiveChannel、DeleteLiveChannel等。

超出阈值，则返回503。

 建议您延迟几秒后进行重试。

错误响应消息体

当用户访问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
阿里云首页 相关技术圈