错误处理与故障恢复

全面排查并处理 TwexAPI HTTP 状态码、MCP 协议报错、配额耗尽异常及写操作重试策略。

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

REST 统一响应数据结构

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

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

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

常见 HTTP 状态码与恢复策略

账户配额管理与余额查询

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

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 校验错误时，应立即停止自动分页循环，修正入参后再恢复。

写操作的错误恢复规则

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

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

MCP 协议层错误排查

1. 工具执行前的握手鉴权失败

当 MCP 客户端鉴权凭据缺失或错误时，服务端会直接在 JSON-RPC 层面拦截并报错，此时 explore 与 twexapi_request 均不会被执行：

{
  "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 阅读与决策：

{
  "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 语言为例：

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)，推荐采用带上限的指数退避机制：

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

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

相关指南

• 速率限制与并发控制
• 身份认证与鉴权指南
• REST API 接口概览
• MCP 工具列表与调用规范