エラー処理

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 復旧は。

Idempotency-Key で投稿を安全に再試行する

POST /twitter/tweets/create と POST /twitter/tweets/quote は、任意の Idempotency-Key ヘッダーを受け付けます。投稿ごとに新しい値（UUID など）を使い、タイムアウトやネットワークエラーのあとで同じ投稿を再試行するときは同じ値を送ってください。

curl https://api.twexapi.io/twitter/tweets/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ceea-467f-a8d1-1f0b4c2a9e01" \
  -d '{"cookie": "auth_token=...; ct0=...", "tweet_content": "Hello from TwexAPI"}'

キーは 1〜255 文字の表示可能な ASCII 文字で、API キーごとに分かれています。ヘッダーがなければ、リクエストのたびに投稿されます。MCP の twexapi_write は自動でキーを付けるため、10 分以内にまったく同じ呼び出しを繰り返すと最初の結果が返ります。

MCP エラー

ツール実行前の認証失敗

MCP の認証に失敗すると、どのツールも実行されません：

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": 401,
    "message": "Access token is invalid or expired"
  }
}

MCP クライアントから再度サインインするか、x-api-key / Authorization: Bearer を修正してから、ツールを呼び出し直してください。認証エラーのメッセージ一覧は MCP ツールリファレンス にあります。

クレジット残高がない

アカウントのクレジットがなくなっても MCP 接続は維持され、explore は無料で使えます。ただし、その他のツール呼び出しは API を呼ばずにエラー結果を返します：

{
  "error": "No credits left on this TwexAPI account. Top up at https://twexapi.io/dashboard and try again."
}

処理を止めて、ユーザーにチャージを依頼してください。再試行しても解決しません。

twexapi_request または twexapi_write で返る API エラー

下位の REST 呼び出しが失敗した場合は、ツールの結果をそのまま保持してください：

{
  "status_code": 429,
  "endpoint": "get_global_trending_tweets",
  "method": "GET",
  "path": "/twitter/global-trending/tweets",
  "result": {
    "code": 429,
    "msg": "Rate limit exceeded. QPS limit: 2 requests per second",
    "data": []
  }
}

上記の 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 でジョブを再開しないようにしましょう。

フレームワーク別メモ

関連ページ

• エラーリファレンス — エンドポイント別のメッセージ、X エラーコード、再試行の判断
• Rate Limits
• Authentication
• API Overview
• MCP Tools