Skip to main content
リクエストが失敗すると、Sorsaは標準のHTTPステータスコードと、問題を説明するmessageフィールドを含むJSONを返します。このページでは、返される可能性がある各コード、その原因と解決方法を説明します。

エラーレスポンスの形式

すべてのエラーレスポンスは同じ構造です。
messageには、発生した問題が読みやすい文章で記載されます。原因を直接示していることが多いため、調査時にはまずこのフィールドを確認してください。

早見表

400 Bad Request

パラメーターが無効または不足しているため、リクエストを処理できませんでした。 よくある原因
  • 必須パラメーター(例:linkidusernamequery)がない
  • パラメーターの型や形式が違う(数値が必要な箇所に文字列を渡すなど)
  • POSTリクエストのJSON本文が不正、または空
解決方法: 対象エンドポイントのAPIリファレンスを確認し、必須パラメーターがすべて正しい形式で指定されていることを確かめてください。POSTリクエストではContent-Type: application/jsonを設定し、本文が有効なJSONであることを確認します。

401 Unauthorized

認証に失敗し、APIがアカウントを識別できませんでした。 よくある原因
  • ApiKeyヘッダーがない
  • ヘッダー名のスペルが違う。ApiKeyを使ってください。HTTPヘッダー名の大文字・小文字は区別されませんが、Api-Keyapi_keyは別の名前です
  • キーの値が間違っている、余分な空白と一緒にコピーされた、または削除済みのキーを使っている
解決方法: ApiKey: your_key_hereという形式でヘッダーが送信されていることと、ダッシュボードでキーが有効であることを確認してください。不明な場合はダッシュボードから直接キーをコピーします。詳しくは認証を参照してください。

403 Forbidden

APIキーは有効ですが、リクエストが拒否されました。 よくある原因
  • リクエストの割り当て量を使い切った(残り0件)
  • サブスクリプションの有効期限が切れた
解決方法: GET /key-usage-infoまたはダッシュボードで残高を確認してください。使い切っている場合は、請求ページで追加購入またはプランのアップグレードを行います。

404 Not Found

要求したリソースが存在しません。 よくある原因
  • Xユーザーがユーザー名を変更した、アカウントを削除した、または凍結された
  • 投稿者がツイートを削除した
  • アカウントやツイートが非公開(保護されている)。Sorsaが取得できるのは公開データのみです
  • エンドポイントのURL自体が間違っている
解決方法: ユーザーやツイートが現在も存在し、X上で一般公開されていることを確認してください。ユーザー名が変わってもユーザーIDは変わりません。保存済みのIDがある場合は、/id-to-username/{user_id}で現在のユーザー名を取得するか、対応するエンドポイントにuser_idを直接渡します。

429 Too Many Requests

毎秒20リクエストのレート制限を超えています。 よくある原因
  • 待機時間のないループでリクエストを送信している
  • 同じAPIキーを共有する複数のワーカーを並列実行している
解決方法: リクエスト間に短い待機時間を入れるか(単一の順次処理ワーカーなら50ms。キーを共有する場合は全体の速度調整が必要)、1秒待機して再試行する処理を追加してください。方法とコード例はレート制限を参照してください。

500 Internal Server Error

Sorsa側で問題が発生しました。 対処方法
  • 1〜2秒待って再試行してください。一時的な500エラーは自然に解消することがよくあります。
  • 再試行しても続く場合や、複数のエンドポイントに影響がある場合は、稼働状況ページで障害情報を確認してください。
  • 解消しない場合は、エンドポイントURL、リクエスト本文、おおよその発生時刻を添えて、[email protected]またはDiscordでサポートに連絡してください。調査資料からAPIキーと認証ヘッダーを取り除いてください。

コードでのエラー処理

堅牢な連携では、想定外のレスポンスで停止するのではなく、各エラーコードに適切に対応します。次はPythonとJavaScriptで再利用できる実装例です。 Python
JavaScript
これらの例は、ネットワークのタイムアウト、接続失敗、4295xxを再試行します。デフォルトの最大試行回数は3回です。それ以外のHTTPエラーでは直ちに失敗します。成功レスポンスでもJSONが無効なら、内容を調査できるよう失敗として扱います。JavaScriptはNode.js 18以降で実行してください。Pythonでは事前にrequestsパッケージをインストールします。

次のステップ