エラー処理
Scrumball API のエラーレスポンスはすべて同じJSON構造です。success は false、code にHTTPステータス、message に簡単な説明が入ります。以下では各ステータスの意味、よくある発生原因、解決方法を説明します。
エラーレスポンスの形式
json
{"success": false,"code": 400,"message": "Bad Request"}
400Bad Request
意味
サーバーがリクエストを解析または受理できず、業務処理に入る前に拒否されました。
よくある原因
- リクエストボディが正しいJSONではありません（search や monitor のタスク作成など POST 系エンドポイント）。
- Content-Type が application/json に設定されていません。
- クエリパラメータの形式が誤っています（例：日付が指定の形式になっていない）。
- パスの綴り間違いにより、意図しないルートに到達しました。
対処方法
- リクエストのパスとHTTPメソッドがエンドポイント参照ページと一致しているか確認してください。
- POST 系エンドポイントでは、リクエストに Content-Type: application/json が含まれているか確認してください。
- JSON検証ツールでボディが正しく解析できるか確認してください。
- エンドポイントページの「必須パラメータ」表を参照し、各パラメータ名と形式を確認してください。
401Unauthorized
意味
リクエストに有効なAPIキーが含まれていないため、サーバーが呼び出し元を識別できません。
よくある原因
- Authorization ヘッダーが送信されていません。
- キーの前に Bearer を付けています（本APIは接頭辞なしの生のキーを使用します）。
- キーが削除または更新されたのに、クライアントが古い値を使い続けています。
- キーをコピーした際に空白や改行が混入しています。
対処方法
- ヘッダーが接頭辞なしの Authorization: YOUR_API_KEY になっているか確認してください。
- ダッシュボード > API Keys で、そのキーが有効な状態かを確認してください。
- キーが無効になっている場合は、新しいキーを作成してサーバー側の環境変数を更新してください。
- まず GET /api/ping で接続を確認し、その後に対象のエンドポイントを調査してください。
403Forbidden
意味
呼び出し元は識別できましたが、このアカウントには当該エンドポイントの利用権限がないか、クォータを使い切っています。
よくある原因
- 現在のプランにこのエンドポイントが含まれていません（オーディエンス分析やリアルタイム取得など）。
- トライアルのクォータを使い切りました。
- サブスクリプションの有効期限が切れています。
- このエンドポイントは当該アカウントではまだ有効化されていません。
対処方法
- ダッシュボード > Usage で残りのクォータを確認してください。
- ダッシュボード > Billing でサブスクリプションの状態と、プランに含まれるエンドポイントの範囲を確認してください。
- 上位のエンドポイントを利用するには、プランをアップグレードするかサポートにご連絡ください。
- 403 と 429 の違いにご注意ください。403 は権限、429 はレート制限の問題です。
404Not Found
意味
リクエストパスが存在しないか、対象のリソースがデータベースに存在しません。
よくある原因
- エンドポイントのパスが誤っているか、廃止されたパスを使用しています。
- HTTPメソッドが一致していません（例：POST 用エンドポイントに GET でリクエスト）。
- 対象のクリエイターアカウントが永続データベースの対象範囲に含まれていません。
- 動画や投稿が削除されたか、非公開に変更されています。
対処方法
- エンドポイント参照ページと照らし合わせて、完全なパスとメソッドを確認してください。
- ベースURLがドキュメントサイトのドメインではなく https://openapi.scdata.cc になっているか確認してください。
- アカウントが見つからない場合は、対応するリアルタイム取得のエンドポイントを呼び出して収集を実行してください。
- 404 と「200 だが data が null」を区別してください。後者はパスは正しくデータが存在しない状態です。
429Too Many Requests
意味
リクエスト頻度が現在のプランの上限を超えたため、サーバー側で制限されました。
よくある原因
- 瞬間的な同時リクエスト数が多すぎます。
- バッチ処理で制御を行わず、短時間に大量のリクエストを送信しています。
- 複数のサービスインスタンスが1つのキーを共有し、呼び出し頻度を調整していません。
- リトライにバックオフがないため、失敗直後の再試行が負荷を増幅しています。
対処方法
- 同時実行数を減らし、単位時間あたりのリクエスト数を制限してください。
- 指数バックオフを実装してください。最初は1秒待ち、以降は倍にしていき、上限は32秒を推奨します。
- バッチ処理はキュー経由の実行に変更し、処理速度を制御してください。
- ダッシュボード > Usage で使用量の推移を確認し、ピーク時間帯を特定してください。
500Server Error
意味
リクエスト処理中にサーバー側で予期しない例外が発生しました。リクエスト自体に問題はありません。
よくある原因
- 上流プラットフォームのデータソースが一時的に利用できません。
- サーバー内部の例外です。
- 特定のパラメータの組み合わせが、想定外のケースを引き起こしました。
対処方法
- バックオフを入れて再試行してください。通常は少し待てば復旧します。
- リクエストの内容一式（パス、全パラメータ、リクエスト時刻、レスポンス）を記録してください。
- 同じリクエストで繰り返し発生する場合は、上記の情報を添えてサポートにご連絡ください。
- クライアント側で 5xx と 4xx を分けて扱ってください。5xx は再試行可能、4xx はリクエストの修正が必要です。