メインコンテンツまでスキップ

APIステータスコードガイド

CAFE24 APIは、リクエストの結果を示すために標準的なHTTPステータスコードを使用します。 それぞれのステータスコードの意味と対処方法を確認しましょう。

✅ 成功レスポンス（2xx）​

200 OK​

GET、PUT、DELETEリクエストが正常に処理されたことを表します。

該当ケース:

  • GET取得リクエスト成功
  • PUT更新リクエスト成功
  • DELETE削除リクエスト成功

例:

curl -X GET 'https://{mallid}.cafe24api.com/api/v2/admin/products' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json'

レスポンス例:

{
  "resource": {
    "product_no": 128,
    "product_name": "サンプル商品",
    "price": 10000
  }
}

201 Created​

POSTリクエストによって新しいリソースが正常に作成されたことを表します。

該当ケース:

  • 商品の登録
  • 注文の作成
  • カテゴリの追加

例:

curl -X POST 'https://{mallid}.cafe24api.com/api/v2/admin/products' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "product_name": "新商品",
    "price": 15000
  }'

207 Multi-Status​

複数のリクエストを処理した際に、オブジェクトごとに異なるステータスを返す場合に使用されます。

該当ケース:

  • 複数商品を一括登録した際、一部のみ成功した場合
  • 一括更新で一部だけ失敗した場合

対処方法: 各オブジェクトのステータスコードを確認し、そのステータスに応じた処理を行ってください。

レスポンス例:

{
  "resource": [
    {
      "product_no": 101,
      "status": 201,
      "message": "正常に作成されました"
    },
    {
      "product_no": 102,
      "status": 400,
      "message": "不正なパラメータです"
    }
  ]
}

❌ クライアントエラー（4xx）​

400 Bad Request​

サーバーがリクエストを理解できません。

該当ケース:

  1. Content-Typeエラー

    • Content-Typeが正しく指定されていない
    • application/typeがjsonではない

  2. エンコーディングエラー

    • URL内の日本語や特殊文字がエンコードされていない

対処方法:

# ❌ 誤った例
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/products?name=商品'

# ✅ 正しい例
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/products?name=%E5%95%86%E5%93%81'

チェック項目:

  • Content-Type: application/json ヘッダーの確認
  • URLパラメータのエンコーディング確認

401 Unauthorized​

認証情報がない、もしくは不正です。

該当ケース:

  1. Access Token未提供

    • Authorizationヘッダーが欠落

  2. Access Tokenが無効

    • 誤ったトークン
    • 期限切れトークン
    • 未知のクライアント

  3. Front API利用時

    • client_idが入力されていない

対処方法:

Admin API:

# ✅ 正しい認証方式
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/admin/products' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json'

Front API:

# ✅ Front APIはclient_idを使用
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/products' \
  -H 'X-Cafe24-Client-Id: {client_id}' \
  -H 'Content-Type: application/json'

チェック項目:

  • 有効なAccess Tokenを発行しているか
  • トークンの有効期限を確認
  • 正しい認証方式の使用（Admin API vs Front API）

403 Forbidden​

認証は通っているが、リソースへのアクセス権限がありません。

該当ケース:

  1. Scope権限の不足

    • Access Tokenはあるが該当Scopeの権限がない

  2. HTTPS未使用

    • HTTPでリクエストしている

  3. 新商品モール未アップグレード

    • 旧商品管理システムを使っている

  4. アプリ削除済み

    • ショッピングモールからアプリが削除された

対処方法:

  1. APIの権限を確認する
# Scope権限が必要な場合は新しいトークンを発行
# デベロッパーセンターでアプリの権限設定を確認
  1. HTTPSを使う
# ❌ 誤った例
curl -X GET 'http://{mallid}.cafe24api.com/api/v2/admin/products'

# ✅ 正しい例
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/admin/products'
  1. アプリを再インストール
    • ショッピングモールからアプリが削除された場合は、再インストールしてください

404 Not Found​

リクエストされたリソースが見つかりません。

該当ケース:

  1. 誤ったURL

    • エンドポイントの誤り
    • リソースパスの誤り

  2. リソースが存在しない

    • 存在しない商品番号
    • 存在しない注文番号

  3. ID不足

    • {#id} の値が欠落している

対処方法:

# APIドキュメントで正しいエンドポイントを確認
# 例: GET /api/v2/admin/products/{product_no}

# ❌ 誤った例
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/admin/prodcuts' # スペルミス

# ✅ 正しい例
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/admin/products/128'

409 Conflict​

同じリソースを同じ内容で重複して更新しようとしました。

該当ケース:

  • 変更データなしのPUTリクエスト

対処方法:

# 修正するデータを送ってください
# 変更点のあるデータのみを送信するように修正

422 Unprocessable Entity​

リクエストデータがスペックと異なる、もしくは無効です。

該当ケース:

  1. 必須パラメータの欠落

    • 必須項目が空欄

  2. 不正な値

    • 誤ったデータ型
    • 範囲外の値
    • 指定スペックと一致しない値

対処方法:

# APIドキュメントで必須パラメータを確認
curl -X POST 'https://{mallid}.cafe24api.com/api/v2/admin/products' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "product_name": "サンプル商品",      # 必須
    "price": 10000,                        # 必須
    "supply_price": 5000,                  # 必須
    "category_no": 1                       # 必須
  }'

チェック項目:

  • 必須パラメータが含まれているか
  • データ型が一致しているか
  • 値の妥当性確認

429 Too Many Requests​

APIリクエストがレート制限を超えました。

該当ケース:

  • バケット超過（瞬間的なリクエスト過多）
  • 許容APIリクエスト数の超過

レート制限ポリシー:

Admin API（リーキーバケット方式）:

  • ショッピングモールごとに設定された呼び出し制限までバケットが溜まる
  • バケットは1秒あたり2減少
  • 秒間2回以下の呼び出しなら制限なし

D.Collection API:

  • IPあたり1分間に最大40回

対処方法:

# レート制限ヘッダーを確認
# X-Api-Call-Limitを監視してリクエストを調整
# 例: X-Api-Call-Limit: 1/40

# 解決策: 少し時間を置いてリトライ
# あるいはリクエスト速度を調整

ベストプラクティス:

// 例: Node.jsでのレート制限ハンドリング
const makeRequest = async (url) => {
  try {
    const response = await fetch(url, {
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      }
    });

    // レート制限ヘッダーを確認
    const remaining = response.headers.get('X-Api-Call-Limit');
    if (!remaining) {
      // レート制限に到達、リトライが必要
      await delay(1000);
      return makeRequest(url);
    }

    return response.json();
  } catch (error) {
    console.error('API Error:', error);
  }
};

🔴 サーバーエラー（5xx）​

500 Internal Server Error​

サーバー内部でエラーが発生しました。

該当ケース:

  • 原因不明のサーバーエラー
  • 一時的なエラー

対処方法:

  • 少し時間を置いてから再度お試しください
  • 継続する場合はデベロッパーセンターまでお問い合わせください

503 Service Unavailable​

サーバーが現在ダウンしている、もしくは利用できません。

該当ケース:

  • サーバーメンテナンス
  • サーバーダウン

対処方法:

  • APIが利用できません
  • サーバーの復旧をお待ちください
  • デベロッパーセンターまでお問い合わせください

504 Gateway Timeout​

リクエスト処理時間を超過しました。

該当ケース:

  • レスポンスのタイムアウト
  • 一時的なネットワーク遅延

対処方法:

# 少し時間を置いてから再度お試しください
# 継続的にタイムアウトが発生する場合はリクエスト構成を見直してください

📊 エラーレスポンスフォーマット​

すべてのAPIエラーは以下のJSON形式で返却されます。

{
  "error": {
    "code": "エラーコード",
    "message": "エラーメッセージ",
    "more_info": {
      // 追加情報
    }
  }
}

🔗 関連ヘッダー​

レート制限関連ヘッダー​

ヘッダー説明
X-Api-Call-Limit現在のAPI呼び出し状況（current/limit）
X-Cafe24-Call-Usage制限に対する呼び出し使用率（%）
X-Cafe24-Call-Remain呼び出し再開までの残り時間（秒）
X-Cafe24-Time-Usage制限に対する処理時間の使用率（%）
X-Cafe24-Time-Remain処理時間再開までの残り時間（秒）

Cafe24 Analytics APIヘッダー​

ヘッダー説明
X-RateLimit-Remaining残りトークン数
X-RateLimit-Requested-Tokensリクエスト済みトークン数
X-RateLimit-Burst-Capacityバケットの最大容量
X-RateLimit-Replenish-Rate秒あたりのトークン補充レート

💡 ベストプラクティス​

1. リクエスト前チェックリスト​

  • ✅ Authorizationヘッダーの確認
  • ✅ Content-Type: application/jsonの確認
  • ✅ HTTPSの利用確認
  • ✅ URLパラメータのエンコーディング確認
  • ✅ 必須パラメータの含有確認

2. エラーハンドリング戦略​

// リトライロジック（指数バックオフ）
const retryWithBackoff = async (fn, maxRetries = 3) => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 || error.status >= 500) {
        const delay = Math.pow(2, i) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
};

3. レート制限管理​

  • レスポンスヘッダーのレート制限情報をモニタリング
  • リクエスト速度の調整
  • バッチリクエストの分散処理

📚 参考資料​