存储

错误代码

了解存储错误代码及其解决方法

存储错误代码

存储中的错误代码会作为响应体的一部分返回。它们对于调试和理解请求出错原因非常有用。 错误代码以以下格式返回：

1
2
3
4
{  "code": "error_code",  "message": "error_message"}

以下是完整的错误代码列表及其描述：

ErrorCode描述StatusCode解决方案
NoSuchBucket指定的存储桶不存在。404验证存储桶名称并确保其在系统中存在，如果存在则可能是您没有访问权限。
NoSuchKey指定的键不存在。404检查键名并确保其在指定存储桶中存在，如果存在则可能是您没有访问权限。
NoSuchUpload指定的上传不存在。404提供的上传ID可能不存在或上传已被中止
InvalidJWT提供的JWT(JSON Web Token)无效。401提供的JWT可能已过期或格式错误，请提供有效的JWT
InvalidRequest请求格式不正确。400检查请求参数和结构，确保符合API要求，错误消息会提供更多详细信息
TenantNotFound指定的租户不存在。404存储服务在配置时出现问题，联系支持
EntityTooLarge上传的实体过大。413验证最大文件限制是否等于或大于您尝试上传的资源，您可以在项目设置中修改此值
InternalError服务器内部错误。500检查服务器日志以确定内部错误原因。如果您认为是存储错误，请联系支持
ResourceAlreadyExists指定的资源已存在。409使用不同的名称或标识符以避免冲突。使用x-upsert:true头来覆盖资源。
InvalidBucketName指定的存储桶名称无效。400确保存储桶名称遵循命名规范且不包含无效字符。
InvalidKey指定的键无效。400验证键名并确保其遵循命名规范。
InvalidRange指定的范围无效。416确保提供的范围在文件大小范围内并遵循HTTP Range规范
InvalidMimeType指定的MIME类型无效。400提供有效的MIME类型，确保使用标准MIME类型格式
InvalidUploadId指定的上传ID无效。400提供的上传ID无效或缺失。确保提供有效的上传ID
KeyAlreadyExists指定的键已存在。409使用不同的键名以避免与现有键冲突。使用x-upsert:true头来覆盖资源。
BucketAlreadyExists指定的存储桶已存在。409为存储桶选择唯一的名称以避免与现有存储桶冲突。
DatabaseTimeout访问数据库时发生超时。504检查数据库性能并增加默认连接池大小。如果错误仍然存在，请升级您的实例
InvalidSignature提供的签名与计算签名不匹配。403检查您提供的签名格式是否正确，更多信息请参考SignatureV4
SignatureDoesNotMatch请求签名与计算签名不匹配。403检查您的凭证、访问密钥ID/访问密钥/区域是否正确，参考S3认证文档。
AccessDenied对指定资源的访问被拒绝。403检查您是否有正确的RLS策略允许访问此资源
ResourceLocked指定的资源被锁定。423资源被锁定时无法修改。请等待后重试请求
DatabaseError访问数据库时发生错误。500检查数据库日志和系统配置以识别并解决数据库错误。
MissingContentLength缺少Content-Length头。411确保请求中包含Content-Length头并提供正确的值。
MissingParameter请求中缺少必需参数。400提供所有必需参数以满足API要求。消息字段会包含更多详细信息
InvalidUploadSignature提供的上传签名无效。403MultiPartUpload记录在上传过程中被修改，签名不匹配。请不要修改上传记录
LockTimeout等待锁时发生超时。423无法在指定超时时间内获取锁。请等待后重试请求
S3Error发生与Amazon S3相关的错误。-参考Amazon S3文档或联系支持以解决S3错误。
S3InvalidAccessKeyId提供的AWS访问密钥ID无效。403验证提供的AWS访问密钥ID并确保其正确且有效。
S3MaximumCredentialsLimit已达到凭证的最大数量限制。400已达到凭证的最大数量限制。
InvalidChecksum实体的校验和不匹配。400重新计算实体的校验和并确保其与请求中提供的校验和匹配。
MissingPart实体的部分内容缺失。400确保在完成操作前请求中包含实体的所有部分。
SlowDown请求速率过高已被限流。503降低请求速率或实现指数退避和重试机制以处理限流情况。

遗留错误代码

在我们过渡到新的错误代码系统期间，您可能仍会看到以下错误格式：

1
2
3
4
5
{  "httpStatusCode": 400,  "code": "error_code",  "message": "error_message"}

以下是最常见错误代码及其解决方案列表：

404 not_found

表示资源未找到或您没有访问该资源的正确权限

解决方案：

  • 添加RLS策略以授予资源访问权限。详见我们的访问控制文档
  • 确保包含用户Authorization请求头
  • 确认对象是否存在

409 already_exists

表示资源已存在

解决方案：

  • 使用upsert功能来覆盖文件。了解更多此处

403 unauthorized

您没有执行此请求的权限

解决方案：

  • 添加RLS策略以授予权限。详见我们的访问控制文档
  • 确保包含用户Authorization请求头

429 too many requests

当大量客户端同时与存储服务交互且连接池达到max_clients限制时，通常会出现此问题

解决方案：

  • 增加连接池的max_clients限制
  • 升级到更大的项目计算实例

544 database_timeout

当大量客户端同时使用存储服务且Postgres没有足够的可用连接来高效处理存储请求时，会出现此问题

解决方案：

  • 增加连接池的pool_size限制
  • 升级到更大的项目计算实例

500 internal_server_error（内部服务器错误）

当出现未处理的错误时会发生此问题。

解决方案：