错误代码

在 SDK 中处理存储错误 #

🌐 Handling Storage errors in SDKs

使用 Supabase SDK 时，存储错误会提供详细信息，帮助你调试问题：

🌐 When using the Supabase SDKs, storage errors provide detailed information to help you debug issues:

1
try {
2
  const { data, error } = await supabase.storage.from('avatars').download('avatar.png')
3
4
  if (error) {
5
    // Access error details
6
    console.log('Error code:', error.error)
7
    console.log('Error message:', error.message)
8
    console.log('HTTP status:', error.status)
9
    console.log('Status code:', error.statusCode)
10
  }
11
} catch (err) {
12
  console.error('Unexpected error:', err)
13
}

存储错误代码 #

🌐 Storage error codes

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

🌐 Error codes in Storage are returned as part of the response body. They are useful for debugging and understanding what went wrong with your request. The error codes are returned in the following format:

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

这里是所有错误代码及其说明的完整列表：

🌐 Here is the full list of error codes and their descriptions:

遗留错误代码 #

🌐 Legacy error codes

由于我们正在过渡到新的错误代码系统，你可能仍然会看到以下错误格式：

🌐 As we are transitioning to a new error code system, you might still see the following error format:

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

这里列出了一些最常见的错误代码及其可能的解决方法：

🌐 Here's a list of the most common error codes and their potential resolutions:

404 not_found#

表示找不到资源，或者你没有正确的权限访问它 解决方法:

🌐 Indicates that the resource is not found or you don't have the correct permission to access it Resolution:

• 添加 RLS 策略以授予对资源的权限。更多信息请参阅我们的访问控制文档。
• 确保你包含用户 Authorization 的头信息
• 确认对象存在

409 already_exists#

表示资源已存在。 解决方法：

🌐 Indicates that the resource already exists. Resolution:

• 使用 upsert 功能来覆盖文件。更多信息请点击这里。

403 unauthorized#

你没有权限执行此请求 解决方法：

🌐 You don't have permission to action this request Resolution:

• 添加 RLS 策略以授予权限。更多信息请查看我们的 访问控制文档。
• 确保你包含用户 Authorization 的头信息

429 too many requests#

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

🌐 This problem typically arises when a large number of clients are concurrently interacting with the Storage service, and the pooler has reached its max_clients limit.

决议:

• 增加连接池的最大客户端限制。
• 在这里升级到更大的项目计算实例。

544 database_timeout#

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

🌐 This problem arises when a high number of clients are concurrently using the Storage service, and Postgres doesn't have enough available connections to efficiently handle requests to Storage.

决议:

• 增加池化器的 pool_size 限制。
• 在这里升级到更大的项目计算实例。

500 internal_server_error#

这个问题发生在存在未处理错误的情况下。 解决方法：

🌐 This issue occurs where there is a unhandled error. Resolution:

• 在这里向存储团队提交支持工单 here