错误处理与故障恢复

全面排查并处理 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 状态码与恢复策略

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

账户配额管理与余额查询

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

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

若收到提示额度不足的 403 报错：

立即暂停所有正在高频轮询该 API 的自动化工作流或 Agent 工具调用。
登录 TwexAPI 控制台核实账户当前余额并完成充值。
充值成功后，从本地持久化保存的最后游标位置无缝恢复任务。

分页拉取的分段安全重试

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

务必将当前页的 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 配置与防重写入最佳实践请查阅。

用 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"}'

用相同的 key 重试	结果
第一次请求已成功（24 小时内）	返回第一次的响应，并带上响应头 `Idempotent-Replayed: true`。不会再次发推，也不会再扣额度。
第一次请求仍在执行	返回 `409`。稍等片刻后用相同的 key 重试。
请求体不同	返回 `422`。发不同的推文请换一个新 key。
第一次请求失败	会重新执行。失败的请求不会占用 key。

key 由 1 到 255 个可见 ASCII 字符组成，按 API 密钥隔离。不带这个请求头时，每次请求都会发推。MCP 的 twexapi_write 调用会自动带上 key：10 分钟内重复完全相同的调用，会返回第一次的结果。

MCP 协议层错误排查

1. 工具执行前的认证失败

MCP 认证失败时，任何工具都不会执行：

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

从 MCP 客户端重新登录，或修正 x-api-key / Authorization: Bearer，然后重新调用工具。全部认证错误信息见 MCP 工具参考。

2. 额度已用完

账号额度用完时，MCP 连接仍然有效，explore 也免费可用，但其他工具调用会直接返回错误结果，不会调用 API：

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

请停止并提醒用户充值，重试没有意义。

3. 通过 `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 错误封装为语言原生的强类型异常。在业务任务边界捕获异常后，请分别提取 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

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

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