ステータスコード及びエラーメッセージ

  • cafe24 APIを呼び出しする際に発生するエラーメッセージの形式とコードを定義します。
  • エラーコードは、Http Response Codeを基に拡張して提供します。

APIエラーコード

  • エラーコードは、Http Response Code規則から拡張され提供します。
  • エラーコード仕組み
エラーコード仕組み
Response Class 説明
2XX Success(成功)
4XX Client Error(クライアントエラー)
5XX Server Error(サーバーエラー)
  • 4xxが発生した場合は、リクエストフォームをもう一度確認し、5xxエラーが継続的に発生する場合は、cafe24 デベロッパーまでお問合せください。

  • ステータスコードの詳細
ステータスコードの詳細
Code エラーメッセージ Header 発生するケース
200 Success OK GET成功、PUT成功、DELETE成功時
201 Successfully created Created POST成功時
207 Multi-status exists. Multi Status 多数のリクエストのステータスが異なる場合
400 Content-type is not an application/json in the header. Bad Request クライアントのリクエストに異常があります。
1) Content-Typeが間違って指定されている。
2) application/typeがjsonではない。
400 Bad Request Bad Request 要請API URLに特殊文字をエンコードしないでそのまま使用した場合
401 Authority to access is not valid. Unauthorized 1) AccessTokenなしで呼び出しした場合
2) AccessTokenが有効ではない場合
3) AccessTokenの期限切れの場合
4) クライアントが不正な場合
401 API cannot be used. Please enter the App key. Unauthorized Front API使用時client_idを未入力した場合
403 No authority to access Forbidden 1) AccessTokenはあるが、Scopeに権限なし。
2) Front APIから見られないように権限が設定されている
403 It is not the https protocol. Forbidden httpsプロトコルがない場合
403 It is not a new product shopping mall. Forbidden (新)商品ショップではない場合
403 This app is deleted. Receive the consent of the operator again. Forbidden (Admin API呼び出しの時)ショッピングモールで、同アプリが削除された場合
403 This app is not installed. Receive the consent of the operator again. Forbidden (Front API呼び出しの時)ショッピングモールで、同アプリが削除された場合
404 No API found. Not Found 1) API URLを間違って呼び出しした場合
2) リソースが見つからない場合
404 The ID of the entity is not valid. Not Found {#id}がない。
422 An invalid request is entered. Unprocessable Entity 照会/処理リクエスト時、値が定義されている内容と異なる場合
1) 必須パラメータ漏れ
2) 値が定義されている内容と異なる場合
429 Too much requests occur. Too many request 照会(GET)リクエスト時、定義されていないパラメータを入力
500 A temporary server error occurs. Internal Server Error サーバー内部エラー、不明なエラー
503 You cannot use the service. Service Unavailable サーバーがダウンした場合。
503 The current API cannot be used. Service Unavailable サーバーがダウンした場合。APIを使用できない。
504 Gateway time-out Gateway Timeout リクエスト期限超え(Timeout)

エラーの解決方法

  • 主なエラーケースについて解決ガイドを提供します。
  • エラーの解決方法
エラーの解決方法
Status Code エラーメッセージ エラー解決方法
207 Multi-status exists. エラーステータスをオブジェクトごと確認し、各ステータスによって対応します。
400 Content-type is not an application/json in the header. リクエスト時「Content-Type」が application/jsonになっているかを確認します。
400 Bad Request リクエストAPI URLに日本語または記号をURLインコーディングしたか確認します。
401 Authority to access is not valid. 有効な発行手続きにより発行されたAccessTokenを使用された確認します。
401 API cannot be used. Please enter the App key. 有効なクライアントIDを使用したかどうかを確認します。
403 No authority to access APIを呼び出しする権限があるかAPIのScopeまたはショップの設定を確認します。
403 It is not the https protocol. APIリクエスト時 httpsでリクエストしたか確認します。
403 It is not a new product shopping mall. ショップが(新)商品管理にアップグレードされてから使用できます。
403 This app is deleted. Receive the consent of the operator again. ショッピングモールにアプリが設置されたかどうかを確認後アプリを再インストールします。
403 This app is not installed. Receive the consent of the operator again. ショッピングモールにアプリが設置されたかどうかを確認後アプリを再インストールします。
404 No API found. エンドポイントURLのエラーがあるかAPIドキュメントを参考して確認します。
404 The ID of the entity is not valid. 要請したエンドポイントのEntity IDが実際に存在する値であるかを確認します。
422 An invalid request is entered. API ドキュメント参考にし、必須パラメータが入力されてない場合や、有効ではない値が入力されたか確認します。
429 Too much requests occur. API最大許可リクエスト件数を超えないようにしばらくたってから再度リクエストします。
500 A temporary server error occurs. 一時的にエラーが発生しました。しばらくたってから再度実行します。
503 You cannot use the service. cafe24 デベロッパーまでお問合せください。
503 The current API cannot be used. cafe24 デベロッパーまでお問合せください。
504 Gateway time-out 一時的にエラーが発生し、レスポンスが遅延しています。しばらくたってから再度お試しください。

エラーメッセージ仕組み

  • エラーメッセージの仕組みは、3つの形(Request・Response・Biz logic)で分け、提供します。
  • レスポンスメッセージ基本仕組み

HTTP/1.1 status
{
   "リソース": [
     {
       "key": value,
       "key": "value"

     }
   ]
}

  • エラーメッセージ仕組み : Request仕様のエラーサンプル
説明 : Biz Logic 実行前、リクエストパラメータの仕様をチェック時エラーが発生した場合

HTTP/1.1 422 Unprocessable Entity
{
   "error": {
     "code": 4220,
     "message": "画像タイプ項目が正しい値ではありません。(parameter.image_upload_type)"

   }
}

  • エラーメッセージ仕組み : Response仕様のエラーサンプル
説明 : Biz Logic 実行前、レスポンスの属性値の仕様をチェック時エラーが発生した場合

HTTP/1.1 200 OK
{
   "error": {
     "code": 4003,
     "message": "アイコン一覧項目が配列最大サイズ5を超えました。 (properties.icon)"

   }
}

  • エラーメッセージ仕組み : Biz logic 実行エラーサンプル
説明 : Biz Logic 実行時エラーが発生した場合

HTTP/1.1 500 Internal Server Error
{
   "error": {
     "code": "5002",
     "message": "DB 入力失敗,",
     "more_info": {
       "event_no": "1"
     }

   }
}

  • エラーメッセージ仕組み : fail collection
説明 : 複数のrequestにエラーが発生した場合

HTTP/1.1 500 Internal Server Error
{
   "errors": [
     {
       "code": "5002",
       "message": "DB 入力失敗,",
       "more_info": {
         "event_no": "1"
       }

     },
     {
       "code": "5002",
       "message": "DB 入力失敗,",
       "more_info": {
         "event_no": "2"
       }

     }
   ]
}

  • エラーメッセージ仕組み: success&fail collection
説明 : 複数のrequestに成功とエラーが同時に発生した場合

HTTP/1.1 200 OK
{
   "products": [
     {
       "event_no": "1",
       "item_code": "TEST_123",
       "item_value": "test"

     }
   ],
   "errors": [
     {
       "code": "5002",
       "message": "Failed to insert database",
       "more_info": {
         "event_no": "2"
       }

     }
   ]
}

その他

  • 定義されたエラーコード以外、発生できるエラーについての参考資料です。
  1. SSL 認証書がないステータスから個人情報(private)と関係のあるエリアにアクセスする場合。
    個人情報が含まれたAPIを呼び出し時、SSLのみアクセス可能のため、APIに個人情報が含めているかによってプロトコルを対応します。
       - PUBLIC : サイトにアクセスしたプロトコルでAPIを呼び出し
       - PRIVATE : httpsのみAPI呼び出し

      ユーザーがアクセスしたプロトコルと同一プロトコルでAPIの呼び出しが必要、問題を事前に防止するため、相対パスを利用することを進めます。
       - 例) https://{{domain}}/api/v2/products → /api/v2/products
     
  2. Front APIのため、Javascript SDK提供
      Front APIのみ利用して開発されたAppのSSLアクセス及び相対パス問題を解決するためにFront API Javascript SDKを提供します。