エラー処理

TwexAPI の HTTP エラー、MCP ツール失敗、クレジット制限、書き込みアクションのリトライから復旧する。

TwexAPI のエラーは 2 層に分かれます。MCP JSON-RPC エラー（ツール実行前の認証）と REST HTTP エラー（API に到達した後）。ステータスコード、レスポンスボディ、カーソル、ID を保持し、リトライと人間による確認を安全に保ちましょう。

REST レスポンスエンベロープ

成功時:

{
  "code": 200,
  "msg": "success",
  "data": {}
}

HTTP ステータスが 2xx でない場合、ボディに code があっても失敗として扱います。ボディ全体、リクエストパス、消費済みカーソルをログに残してください。

HTTP ステータス別の復旧

クレジットと残高

従量課金の読み取り・書き込みはアカウントクレジットを消費します。多ページ処理では、長時間ジョブの前後に残高を確認しましょう。

curl --request GET \
  --url 'https://api.twexapi.io/balance' \
  --header 'Authorization: Bearer YOUR_API_KEY'

403 がクレジットやアクセスに言及する場合:

1. API を叩き続けるスケジュールジョブを停止。
2. ダッシュボードで残高を確認。
3. クレジット復旧後、最後に保存したカーソルから再開。

ページネーション安全なリトライ

検索、フォロワー、タイムライン、DM 履歴では:

• next_cursor、has_next_page、task_id をエージェント会話の外に保存。
• 429 や 5xx 後は同じカーソルでリトライ（次ページではない）。
• 400、404、422 後は ID とクエリパラメータを確認してからリトライ。

書き込みアクション

書き込みエンドポイント（ツイート、返信、いいね、フォロー、DM 送信）には以下が必要です。

• 有効な TwexAPI API キー
• リクエスト上の保存済み Twitter cookie または auth_token

復旧ルール:

TwexAPI は別途の書き込みポーリング API を提供していません。副作用を繰り返す前に、べき等な読み取りチェック（ツイート参照、DM ステータス）を優先。cookie 設定と 403 復旧は。

MCP エラー

ツール実行前の認証失敗

MCP 認証が失敗すると、explore と twexapi_request は実行されません。

{
  "jsonrpc": "2.0",
  "error": {
    "code": 401,
    "message": "Missing MCP API token"
  }
}

MCP クライアントの x-api-key または Authorization: Bearer を修正し、ツール呼び出しを再実行してください。

twexapi_request 経由の API エラー

基盤 REST 呼び出しが失敗した場合、ツール結果を保持します。

{
  "status_code": 403,
  "endpoint": "get_global_trending_tweets",
  "method": "GET",
  "path": "/twitter/global-trending/tweets",
  "result": {
    "detail": "Credits exhausted or action not allowed."
  }
}

上記 HTTP 復旧表と同じ対応を適用。ルートが変わった可能性がある場合のみ explore を再呼び出し — モデルに新パスを推測させないでください。

SDK と CLI のエラー

生成 SDK は HTTP 失敗を言語ネイティブな例外にマップします。ジョブ境界で catch し、ステータスコードとレスポンスボディをログ、429/5xx はリトライポリシーへ。

Python 例:

import requests

try:
    response = requests.get(
        "https://api.twexapi.io/balance",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        timeout=30,
    )
    response.raise_for_status()
except requests.HTTPError as exc:
    status = exc.response.status_code
    body = exc.response.text
    if status == 429:
        # Back off, preserve cursor, retry later
        ...
    elif status in (400, 404, 422):
        # Fix input; do not retry unchanged
        ...
    raise

言語別パターンは各 SDK ページ を参照してください。

リトライバックオフテンプレート

429 と 5xx には上限付き指数バックオフ:

retry_delays_seconds = [5, 15, 45, 120]

for delay in retry_delays_seconds:
    response = call_twexapi()
    if response.ok:
        break
    if response.status_code in (429, 500, 502, 503, 504):
        time.sleep(delay)
        continue
    break  # 4xx other than 429: stop and fix input

バックオフは Rate Limits と組み合わせ、429 直後にフル QPS でジョブを再開しないようにしましょう。

フレームワーク別メモ

関連ページ

• Rate Limits
• Authentication
• API Overview
• MCP Tools