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

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

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

成功時:

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

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

## HTTP ステータス別の復旧

| ステータス | 意味 | 対処法 |
| --- | --- | --- |
| `400` | 無効なクエリ、欠落フィールド、不正なボディ | 入力を修正。**そのまま**リトライしない。 |
| `401` | API キー欠落または無効 | [dashboard](https://twexapi.io/dashboard) から認証情報を差し替え。`Authorization: Bearer` 形式を確認。 |
| `403` | クレジット枯渇、アカウント制限、アクション不可 | [Get Balance](/api-reference/balance-endpoints/get-balance-api-balance-get) を確認。チャージするか、書き込みステップを外す。 |
| `404` | ツイート、ユーザー、リスト、リソース未検出 | ID、スクリーン名、カーソルの鮮度を確認。 |
| `422` | 構造化入力の検証失敗 | エンドポイントページのスキーマフィールドを修正。そのままリトライしない。 |
| `429` | レート制限超過 | [Rate Limits](/guides/rate-limits) でバックオフ。`next_cursor` と完了行を保持。 |
| `5xx` | 一時的なサービスまたは上流取得失敗 | 指数バックオフと上限付きでリトライ。 |

## クレジットと残高

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

```bash
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`

復旧ルール:

| 状況 | 推奨アクション |
| --- | --- |
| 書き込みで `401` | リトライ前に API キーと cookie 認証情報を修正。 |
| 書き込みで `403` | クレジットと接続アカウントの権限を確認。 |
| 成功が曖昧 | 読み取りエンドポイントでツイート、DM、エンゲージメント状態を確認してから重複実行。 |
| エージェントワークフロー | `read_only: false` の MCP 呼び出し前に人間の承認を必須に。 |

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

## MCP エラー

### ツール実行前の認証失敗

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

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

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

### `twexapi_request` 経由の API エラー

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

```json
{
  "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 例:

```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 ページ](/sdks) を参照してください。

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

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

```python
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](/guides/rate-limits) と組み合わせ、`429` 直後にフル QPS でジョブを再開しないようにしましょう。

## フレームワーク別メモ

| 実行環境 | 推奨事項 |
| --- | --- |
| [LangChain](/guides/langchain) | ハンドオフモデルを検証。`401` でグラフを停止。 |
| [Prefect](/guides/prefect) | ジッター付きタスクリトライ。カーソルはタスク状態に保存。 |
| [n8n / Zapier / Make](/guides/no-code-workflow-handoff) | `401`/`403` は運用アラートへ。`429` リプレイは遅延。 |
| [MCP agents](/mcp/agent-handoff) | 部分成功後に `next_cursor` を破棄しない。 |

## 関連ページ

- [Rate Limits](/guides/rate-limits)
- [Authentication](/authentication)
- [API Overview](/api-reference/overview)
- [MCP Tools](/mcp/tools)