错误 | 文档 - Roblox 创作者中心

以下部分描述了开放云API的错误处理。由于不同端点和验证层之间的实现差异，错误响应的格式可能会有显著不同。

网关错误

对于身份验证或路由问题，开放云v1和v2 API可能以以下格式返回错误：

示例网关错误
{
  "errors": [
    {
      "code": 0,
      "message": "无效的API秘钥"
    }
  ]
}

开放云v2

开放云v2 API通常在API端点内部发生错误时遵循一致的错误格式。

标准v2错误格式

开放云v2 API以以下格式返回错误：

code - 表示错误类型的字符串（例如 INVALID_ARGUMENT, NOT_FOUND）。
message - 解释错误的人类可读消息。
details - 可选数组，包含额外的错误特定信息。

示例v2错误
{
  "code": "INVALID_ARGUMENT",
  "message": "请求中的用户ID无效。"
}

示例v2错误与详细信息
{
  "code": "INVALID_ARGUMENT",
  "message": "提供的过滤器无效。",
  "details": [
    {
      ...
    }
  ]
}

v2错误代码

下表描述了v2 API响应中code的可能值。

代码	HTTP状态	描述
INVALID_ARGUMENT	400	您传递了一个无效的参数，例如无效的universeId。您可能还缺少或无效的头部，例如Content-Length和Content-Type。
PERMISSION_DENIED	403	您的请求没有足够的权限或范围来执行该操作。
NOT_FOUND	404	系统无法找到您指定的资源，例如数据存储条目。
ABORTED	409	操作被中止。
RESOURCE_EXHAUSTED	429	您没有足够的配额来执行该操作，通常是由于发送过多的请求。
CANCELLED	499	系统终止请求，通常是由于客户端超时。
INTERNAL	500	内部服务器错误，通常是由于服务器错误。
NOT_IMPLEMENTED	501	服务器未实现该API方法。
UNAVAILABLE	503	服务不可用，通常在服务器宕机时返回。

开放云v1

开放云v1 API的错误响应格式不一致。格式取决于特定端点、错误类型以及错误在请求处理管道中的发生位置。

大多数v1端点以以下三种格式之一返回错误：

示例v1错误与错误字段
{
  "error": "INVALID_ARGUMENT",
  "message": "无效的光标。",
  "errorDetails": [
    {
      "errorDetailType": "DatastoreErrorInfo",
      "datastoreErrorCode": "InvalidCursor"
    }
  ]
}

示例v1错误与代码字段
{
  "code": "INVALID_ARGUMENT",
  "message": "无效的光标。"
}

示例v1详细验证错误
{
  "errors": {
    "assetId": ["值 'a' 无效。"]
  },
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "发生一个或多个验证错误。",
  "status": 400,
  "extensions": {
    "traceId": "00-427917f0fc3b8375ee33e4603a7f0693-f3f6ad560ff1a122-00"
  }
}

v1错误代码

下表描述了v1 API响应中error或code的可能值：

HTTP状态代码	错误	描述
400	INVALID_ARGUMENT	您传递了一个无效的参数，例如无效的universeId。您可能还缺少或无效的头部，例如Content-Length和Content-Type。
403	INSUFFICIENT_SCOPE	该请求需要比访问令牌提供的更高权限。
403	PERMISSION_DENIED	您的请求没有足够的范围来执行该操作。
404	NOT_FOUND	系统无法找到您指定的资源，例如数据存储。
409	ABORTED	由于冲突，该操作已中止，例如发布不属于宇宙的地方。
429	RESOURCE_EXHAUSTED	您没有足够的配额来执行该操作，通常是由于发送过多的请求。
499	CANCELLED	系统终止请求，通常是由于客户端超时。
500	INTERNAL	内部服务器错误。通常是服务器错误。
501	NOT_IMPLEMENTED	服务器未实现该API方法。
503	UNAVAILABLE	服务不可用。通常是服务器宕机。