錯誤 | 文件 - Roblox 創作者中心

以下部分描述了 Open Cloud APIs 的錯誤處理。由於端點和驗證層之間的實現差異，錯誤響應的格式可能會有很大差異。

網關錯誤

針對身份驗證或路由問題，Open Cloud v1 和 v2 APIs 可能會以以下格式返回錯誤：

範例網關錯誤
{
  "errors": [
    {
      "code": 0,
      "message": "無效的 API 金鑰"
    }
  ]
}

Open Cloud v2

當錯誤發生在 API 端點內部時，Open Cloud v2 APIs 通常遵循一致的錯誤格式。

標準 v2 錯誤格式

Open Cloud v2 APIs 以以下格式返回錯誤：

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	服務不可用，通常在伺服器停機時返回。

Open Cloud v1

Open Cloud v1 APIs 的錯誤響應格式不一致。該格式取決於特定的端點、錯誤類型以及錯誤在請求處理管道中的發生位置。

大多數 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	服務不可用。通常是伺服器故障。