---
title: "错误处理与故障恢复"
description: "全面排查并处理 TwexAPI HTTP 状态码、MCP 协议报错、配额耗尽异常及写操作重试策略。"
---

TwexAPI 在两个不同层级返回错误信息：**MCP JSON-RPC 协议错误**（通常发生在调用工具前的鉴权或协议阶段）与 **REST HTTP 错误**（请求已成功到达 API 网关后的业务或系统级响应）。在构建健壮的自动化系统时，请务必完整持久化保存状态码、响应体、分页游标及业务 ID，以便实现安全幂等的重试与人工排障。

## REST 统一响应数据结构

所有接口在调用成功时，均返回统一的 JSON 封装体：

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

> **重要准则：** 客户端判定请求是否成功，必须以 **HTTP 状态码处于 2xx 区间**为准。当 HTTP 状态码非 2xx 时，即便返回的 JSON 正文中含有 `code` 字段，也必须判定为调用失败。请务必完整记录错误详情、请求接口路径以及当前正在消费的游标。

## 常见 HTTP 状态码与恢复策略

| HTTP 状态码 | 产生原因说明 | 推荐应对措施 |
| --- | --- | --- |
| **`400 Bad Request`** | 查询参数无效、缺少必填字段或 JSON 载荷格式畸形。 | 检查并修正客户端请求参数，**切勿**使用相同输入盲目重试。 |
| **`401 Unauthorized`** | API 密钥缺失、已失效或格式错误。 | 前往 [控制台 (Dashboard)](https://twexapi.io/dashboard) 重新获取密钥，检查是否遗漏 `Authorization: Bearer ` 前缀。 |
| **`403 Forbidden`** | 账户调用配额耗尽、目标账号受限或当前 Key 无权执行该操作。 | 调用 [查询余额接口](/api-reference/balance-endpoints/get-balance-api-balance-get) 确认剩余额度。及时充值，在配额恢复前停止写入流。 |
| **`404 Not Found`** | 指定的推文 ID、用户名、列表或资源不存在，或已被原作者删除。 | 核对业务 ID、Username 拼写及分页游标的有效时限。 |
| **`422 Unprocessable Entity`** | 结构化请求参数未通过 Schema 强校验。 | 对照官方接口文档校验每个字段的类型与枚举值，修正后重发。 |
| **`429 Too Many Requests`** | 触发平台速率限制 (QPS 超限)。 | 严格参考 [速率限制指南](/guides/rate-limits) 进行指数退避等待，必须妥善保存当前的 `next_cursor`。 |
| **`5xx Server Error`** | 服务端临时波动或上游数据源抓取抖动。 | 采用带上限的有抖动指数退避算法进行重试（最多重试 3–5 次）。 |

## 账户配额管理与余额查询

TwexAPI 按照实际请求量消耗账户余额。在执行大规模全量导出或无人值守的定时调度任务前后，建议主动调用余额查询端点：

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

若收到提示额度不足的 `403` 报错：
1. 立即暂停所有正在高频轮询该 API 的自动化工作流或 Agent 工具调用。
2. 登录 TwexAPI 控制台核实账户当前余额并完成充值。
3. 充值成功后，从本地持久化保存的**最后游标位置**无缝恢复任务。

## 分页拉取的分段安全重试

针对推文搜索、粉丝列表、时间线及私信历史等基于游标的分页拉取：

- 务必将当前页的 `next_cursor`、`has_next_page` 以及任务 ID 独立持久化存储在 Agent 易失性上下文之外（如数据库或 Redis）。
- 遇到 `429` 速率限制或 `5xx` 服务端瞬时错误时，**必须重试当前发生错误的同一页游标**，严禁在未成功取得数据时盲目推进至下一页。
- 遇到 `400` 或 `422` 校验错误时，应立即停止自动分页循环，修正入参后再恢复。

## 写操作的错误恢复规则

写操作接口（发推、跟帖回复、点赞、关注、发送私信等）具有不可逆的外部副作用：

| 异常情境 | 推荐处置方案 |
| --- | --- |
| **写操作返回 `401`** | 在重试前，全面核查 API Key 以及请求中携带的 Twitter Cookie / `auth_token` 有效性。 |
| **写操作返回 `403`** | 确认账户额度是否充足，以及关联的 Twitter 账号是否被平台风控禁言。 |
| **网络超时或响应不明确** | 严禁直接发起二次写入！请先调用对应读接口（查询个人最新发帖或私信记录）确认是否已有副作用产生，确认缺失后再重试一次。 |
| **AI Agent 自动化流程** | 在调用任何标记为 `read_only: false` 的写入工具前，必须获得人工明确审批。 |

Cookie 配置与防重写入最佳实践请查阅。

## MCP 协议层错误排查

### 1. 工具执行前的握手鉴权失败
当 MCP 客户端鉴权凭据缺失或错误时，服务端会直接在 JSON-RPC 层面拦截并报错，此时 `explore` 与 `twexapi_request` 均不会被执行：

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

**解决方案：** 在 MCP 客户端配置文件中检查并修正 `x-api-key` 或 `Authorization: Bearer` 请求头。

### 2. 通过 `twexapi_request` 透传的 REST 业务错误
当底层 REST 接口调用失败时，MCP 服务器会将错误详情完整包装在工具返回结果中，供 AI Agent 阅读与决策：

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

**解决方案：** 让 Agent 根据返回的 `status_code` 应用前述 HTTP 恢复策略。严禁让大模型随意编造或猜测不存在的新接口路径 — 路由产生歧义时应重新调用 `explore`。

## SDK 与 CLI 异常捕获范式

官方 SDK 将底层的 HTTP 错误封装为语言原生的强类型异常。在业务任务边界捕获异常后，请分别提取 HTTP 状态码与详细响应体，并将 `429` 和 `5xx` 接入重试引擎。

以 Python 语言为例：

```python
import time
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
    error_body = exc.response.text
    if status == 429:
        # 触发退避机制，保存当前游标，延迟重试
        ...
    elif status in (400, 404, 422):
        # 参数校验失败，告警并修正入参，不可原样重发
        ...
    raise
```

## 标准指数退避重试实现

针对网络抖动 (`5xx`) 与偶发速率限制 (`429`)，推荐采用带上限的指数退避机制：

```python
import time

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):
        print(f"请求失败 ({response.status_code})，休眠 {delay} 秒后重试...")
        time.sleep(delay)
        continue
    # 遇到 400/401/403/404/422 等非重试类状态码立即阻断退出
    break
```

## 主流开发框架与编排工具适配建议

| 开发与编排框架 | 核心实践建议 |
| --- | --- |
| **[LangChain](/guides/langchain)** | 严格校验 Agent 间交接的数据模型；收到 `401` 时立即阻断工作流图执行。 |
| **[Prefect](/guides/prefect)** | 为任务重试增加随机抖动 (Jitter)；分页游标务必持久化存入 Task 状态。 |
| **[n8n / Zapier / Make](/guides/no-code-workflow-handoff)** | 将 `401`/`403` 严重错误路由至即时运维通知节点；遇到 `429` 则配置延迟自动重放。 |
| **[MCP AI Agents](/mcp/agent-handoff)** | 在单次工具调用部分成功后，切勿遗失或丢弃返回的 `next_cursor`。 |

## 相关指南

- [速率限制与并发控制](/guides/rate-limits)
- [身份认证与鉴权指南](/authentication)
- [REST API 接口概览](/api-reference/overview)
- [MCP 工具列表与调用规范](/mcp/tools)