错误代码 · Cloudflare R2 docs

本页记录使用 Workers API 或 S3 兼容 API 时 R2 返回的错误代码，以及建议的修复方法，便于排查问题。

错误返回方式

对于 Workers API，R2 操作会抛出可捕获的异常。错误代码包含在 message 属性的末尾：

try {
  await env.MY_BUCKET.put("my-key", data, { customMetadata: largeMetadata });
} catch (error) {
  console.error(error.message);
  // "put: Your metadata headers exceed the maximum allowed metadata size. (10012)"
}

对于 S3 兼容 API，错误以 XML 形式在响应体中返回：

<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
</Error>

错误代码参考

身份验证与授权错误

错误代码	S3 代码	HTTP 状态	详情	建议修复
10002	Unauthorized	401	缺少或无效的身份验证凭据。	确认 API 令牌或访问密钥凭据正确且未过期。
10003	AccessDenied	403	对请求操作的权限不足。	检查 API 令牌是否对存储桶和操作具有所需权限。
10018	ExpiredRequest	400	预签名 URL 或请求签名已过期。	重新生成预签名 URL 或签名。
10035	SignatureDoesNotMatch	403	请求签名与计算签名不匹配。	验证密钥和签名算法。检查 URL 编码问题。
10042	NotEntitled	403	账户无权使用此功能。	确保账户已订阅 R2。

存储桶错误

错误代码	S3 代码	HTTP 状态	详情	建议修复
10005	InvalidBucketName	400	存储桶名称不符合命名要求。	存储桶名称必须为 3–63 个字符，小写字母数字和连字符，且以字母数字开头和结尾。
10006	NoSuchBucket	404	指定的存储桶不存在。	确认存储桶名称正确且存储桶存在于账户中。
10008	BucketNotEmpty	409	无法删除包含对象的存储桶。	删除存储桶前须先删除其中所有对象。
10009	TooManyBuckets	400	超出账户存储桶数量限制（默认：1,000,000 个存储桶）。	通过限额提升申请表 ↗ 申请提高限额。
10073	BucketConflict	409	存储桶名称已存在。	选择其他存储桶名称。存储桶名称在账户内必须唯一。

对象错误

错误代码	S3 代码	HTTP 状态	详情	建议修复
10007	NoSuchKey	404	指定的对象键不存在。对于 Workers API，`get()` 和 `head()` 返回 `null` 而非抛出异常。	确认对象键正确且对象未被删除。
10020	InvalidObjectName	400	对象键包含无效字符或过长。	使用有效的 UTF-8 字符。键最大长度为 1024 字节。
100100	EntityTooLarge	400	对象超出最大大小（单次上传 5 GiB，分片上传 5 TiB）。	大于 5 GiB 的对象请使用分片上传。对象最大大小为 5 TiB。
10012	MetadataTooLarge	400	自定义元数据超出 8,192 字节限制。	减小自定义元数据大小。所有自定义元数据合计最大 8,192 字节。
10069	ObjectLockedByBucketPolicy	403	对象受存储桶锁定规则保护，无法修改或删除。	等待保留期结束。请参阅存储桶锁定。

上传与请求错误

错误代码	S3 代码	HTTP 状态	详情	建议修复
10033	MissingContentLength	411	需要 `Content-Length` 请求头但缺失。	在 PUT/POST 请求中包含 `Content-Length` 请求头。
10013	IncompleteBody	400	请求体在预期 `Content-Length` 之前终止。	确保发送完整请求体。检查网络中断或客户端超时。
10014	InvalidDigest	400	校验和请求头格式错误。	确保校验和正确编码（SHA/CRC 校验和使用 base64）。
10037	BadDigest	400	提供的校验和与上传内容不匹配。	验证数据完整性并重试上传。
10039	InvalidRange	416	请求的字节范围无法满足。	确保范围起始小于对象大小。检查 `Range` 请求头格式。
10031	PreconditionFailed	412	条件请求头（`If-Match`、`If-Unmodified-Since` 等）未满足。	对象的 ETag 或修改时间与条件不匹配。重新获取后重试。请参阅条件操作。

分片上传错误

错误代码	S3 代码	HTTP 状态	详情	建议修复
10011	EntityTooSmall	400	分片小于最小大小（5 MiB），最后一片除外。	确保每个分片（最后一片除外）至少 5 MiB。
10024	NoSuchUpload	404	分片上传不存在或已中止。	确认 `uploadId` 正确。默认情况下，未完成的分片上传在 7 天后过期。请参阅对象生命周期。
10025	InvalidPart	400	完成上传时找不到一个或多个分片。	确认每个分片已成功上传，并使用 `UploadPart` 返回的确切 ETag。
10048	InvalidPart	400	所有非末尾分片必须大小相同。	确保除最后一片外所有分片大小一致。R2 要求分片上传的分片大小统一。

服务错误

错误代码	S3 代码	HTTP 状态	详情	建议修复
10001	InternalError	500	发生内部错误。	重试请求。若持续出现，请查看 Cloudflare Status ↗ 或联系支持。
10043	ServiceUnavailable	503	服务暂时不可用。	使用指数退避重试。查看 Cloudflare Status ↗。
10054	ClientDisconnect	400	客户端在请求完成前断开连接。	检查网络连接并重试。
10058	TooManyRequests	429	超出速率限制。通常由对同一对象键的多个并发请求引起（限制：每个键每秒 1 次写入）。	检查是否有多个客户端访问同一对象键。请参阅 R2 限制。