Weegloo Docs - エラー

リクエストが失敗すると、WEEGLOOは一貫した形式のエラー本文とHTTPステータスコードを併せて返します。レスポンス本文の形は、どのAPI(CMA・CDA・ACMA・ACDA・Upload・Auth)で失敗したかに関係なく同じです。そのため、一つの形式の扱い方さえ知っていれば、すべてのエラーを同じ方法で分岐処理できます。このページでは、その共通形式とよく遭遇するエラーコードを一か所にまとめます。

エラーレスポンス形式

エラー本文は次のような形です。以下は存在しないWebHostingを照会したときに受け取ったレスポンスです。

{
  "requestId": "GeR3sEbvWdgvv9eW2NXeanpj2wo6qbkVXgIW7Qd3ea6",
  "sys": {
    "id": "RxcgyPTSuk4GDy6s",
    "type": "NotFound",
    "code": "WGL404001",
    "timestamp": 1781785683556
  },
  "details": {
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } }
  },
  "reason": "WebHosting(...) has been deleted or does not exist.",
  "suggestion": "Please verify WebHosting and try again."
}

各キーの意味は次のとおりです。

キー	型	説明
`requestId`	string	このリクエストのトレース識別子。サポートに問い合わせる際にこの値を併せて伝えると、該当のリクエストを素早く見つけられます。
`sys.type`	string	エラー分類。`Unauthorized`・`Forbidden`・`NotFound`・`Unprocessable`・`Conflict`・`TooManyRequest`などの大きな区分を表します。
`sys.code`	string	詳細エラーコード(例: `WGL409005`)。コード単位で分岐処理する際にこの値を使います。
`sys.timestamp`	integer	エラー発生時刻(epoch millis)。
`reason`	string	人が読むための失敗理由。
`suggestion`	string	解決を助けるヒント。
`details`	object (任意)	付加情報。関連リソースを指す`Refer`、検証エラー項目の一覧(`errors`)などが入ります。エラーの種類によっては存在しない場合があります。

分岐処理はsys.type(大きな区分)またはsys.code(詳細コード)のうち、必要な単位で行います。同じsys.typeでもsys.codeが異なれば原因が異なるため、正確な処理が必要な場合はsys.codeを基準にしてください。

検証に失敗すると、details.errorsに違反した項目が入ります。以下は、本文にスキーマにない属性を入れて検証に失敗したレスポンスです。

{
  "requestId": "yJ8KpQ2mWtnLrZ4Xv7BcEadfh3sNuMvKbGT5Pq9wRsx",
  "sys": {
    "id": "Lm2Nq9Tr8KdW4xZc",
    "type": "BadRequest",
    "code": "WGL400006",
    "timestamp": 1781776000000
  },
  "details": {
    "errors": [
      { "path": "", "message": "property 'X' is not defined in the schema", "property": "X" }
    ]
  },
  "reason": "Some values do not satisfy validation rules.",
  "suggestion": "Please check the request body and try again."
}

details.errorsの各項目は、違反した位置(path)と説明(message)、関連する属性名(property)を含みます。項目が複数ある場合は、違反した値ごとに一つずつ入ります。

よく遭遇するコード

以下はよく遭遇するエラーコードです。

コード	分類	意味	よくある状況
`WEB401001`	`Unauthorized`	トークンが無効	`Authorization` Bearerトークンが期限切れか、誤っています。
`WGL403001`	`Forbidden`	権限なし	呼び出し元のロールがその操作を許可していません。
`WGL404001`	`NotFound`	リソースが存在しないか削除済み	誤った`sys.id`で照会したか、まだ設定されていない機能を呼び出しました(例: カスタムドメイン未接続)。
`WGL400006`	BadRequest	本文の値が検証ルールに違反	誤ったフィールドキーや型で本文を送りました。違反した項目は`details.errors`に入ります。
`WGL409005`	`Conflict`	リソースがその間に更新された	`X-Weegloo-Version`ヘッダーが欠けているか、現在のバージョンと異なります(規約を参照)。
`WGL422007`	`Unprocessable`	公開状態のためアーカイブできない	ContentやMediaをアーカイブするには、先に公開取り消しが必要です。
`WGL422009`	`Unprocessable`	公開状態のため削除できない	公開されたContentやMediaを削除するには、先に公開取り消しが必要です。
`WGL429001`	`TooManyRequest`	プラン上限の超過	Organization・Spaceなどのリソース作成数が現在のプラン上限を超えました。プランを上げると上限が増えます。

上記のコードはよく遭遇する一部です。このほかにも、操作やリソースに応じてさらに多くのコードが存在する場合があります。どのコードを受け取っても、sys.typeで大きな区分を把握し、reason・suggestionで具体的な原因と解決の方向を確認してください。

規約: WGL409005を回避するためのX-Weegloo-Version同時実行ルール。
システムプロパティ (sys): 公開状態(status)と、WGL422007・WGL422009が指すライフサイクル。

エラーレスポンス形式

よく遭遇するコード

関連ドキュメント