エラー | 文書 - Roblox クリエーターハブ

以下のセクションでは、Open Cloud API のエラー処理について説明します。エンドポイントや検証レイヤーによって実装の違いがあるため、エラー応答の形式は大きく異なる可能性があります。

ゲートウェイエラー

認証やルーティングの問題がある場合、Open Cloud v1 および v2 API は次の形式でエラーを返すことがあります：

例: ゲートウェイエラー
{
  "errors": [
    {
      "code": 0,
      "message": "無効な API キー"
    }
  ]
}

Open Cloud v2

Open Cloud v2 API は、エラーが API エンドポイント自体内で発生したときに、一般的に一貫したエラー形式に従います。

標準 v2 エラー形式

Open Cloud 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	サービスが利用できません。通常、サーバーがダウンしているときに返されます。

Open Cloud v1

Open Cloud 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": "1 つ以上の検証エラーが発生しました。",
  "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	サービスが利用できません。通常、サーバーがダウンしています。