Twitter API 错误码与 HTTP 状态码参考

排查 TwexAPI 的 Twitter/X API 错误：401 认证失败、403 访问受限、429 限流、invalid auth_token、重复推文、私信限额及安全重试。

TwexAPI 通过 HTTP 状态码报告 Twitter/X API 错误；部分响应还会包含上游 X 错误码。401 需要修正凭据，403 需要检查权限或账号状态，429 需要等待限流解除。重试前应先检查响应体。

本页帮助你排查 Twitter API 错误码、invalid auth_token、重复推文和私信限额。下列路径与当前 API 文档 保持一致。MCP 错误、分页恢复和 SDK 示例请参阅 错误处理。

下列消息和上游错误码是排障示例；不同接口的响应结构和 HTTP 状态码映射可能不同。请结合接口 Schema 与实际响应判断。

快速定位 Twitter API 错误

• HTTP 401 / Invalid auth_token：同时检查 TwexAPI API Key 和写接口使用的 X 会话凭据。参阅 身份认证。
• HTTP 403：根据消息检查额度、私密推文、账号限制或 Premium 要求。重复相同请求不会恢复访问权限。
• HTTP 429 / Too Many Requests：遵守 Retry-After 或 retry_after，区分请求限流和 X 账号每日限额。参阅 速率限制。
• HTTP 500 / 502 / 503：临时读取错误可以按有上限的退避策略重试。写操作重试前，先确认是否已经执行成功。
• X 错误码 187、344 或 502：这些是上游 X 错误码，与 HTTP 状态码不同。查看 X 错误码表 和 重试常见问题。

错误响应格式

保存 HTTP 状态码和完整 JSON 响应体。TwexAPI 响应可能包含 code 和 msg，参数校验错误使用 detail：

{
  "code": 500,
  "msg": "Internal server error"
}

{
  "detail": [
    {
      "loc": ["body", "cookie"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

如果响应包含上游附加信息，也请一并保留：

• error：错误消息（如果返回）。不要假设所有接口都使用这个字段。
• twitter_error_code：X 错误码（如果返回），与 HTTP 状态码不同。例如 X 错误码 502 表示私信限额。
• retry_after：需要等待的秒数（如果返回）。同时遵守 HTTP Retry-After 响应头。

不要要求可选字段一定存在，也不要只按错误消息的精确文本分支。HTTP 状态码非 2xx 时，即使响应体内的 code 不同，也应视为失败。

所有接口的常见错误

任何请求都应检查下列情况；具体错误消息可能不同。

Twitter API HTTP 状态码

X（Twitter）错误码

当响应包含上游 X 错误码时，可参考下表。这些是 X 错误码，不是 HTTP 状态码；并非每个接口都会提供 twitter_error_code。

读取推文与搜索

适用于 POST /twitter/{screen_name}/timeline/page、/twitter/tweets-replies/page 和 /twitter/advanced_search/page。

发推与互动

创建推文

POST /twitter/tweets/create

提交 tweet_content，回复时提供 reply_tweet_id，并通过 cookie 提交 X 凭据。参阅 创建推文或回复。

点赞 / 转推 / 收藏

POST /twitter/tweets/{tweet_id}/like · /twitter/tweets/{tweet_id}/retweet · /twitter/tweets/{tweet_id}/bookmark

DELETE /twitter/tweets/{tweet_id}/like · /twitter/tweets/{tweet_id}/retweet · /twitter/tweets/{tweet_id}/bookmark

删除推文

POST /twitter/tweets/delete-batch

删除单条推文时传入 target_id。省略该字段会选择批量删除；处理错误时务必保留原请求字段。

关注 / 取消关注

POST /twitter/user/follow · DELETE /twitter/user/follow

更新资料 / 头像 / 横幅

POST /twitter/profile

使用 profile_image、profile_banner 提交图片 URL，使用 cookie 提交 X 凭据。

媒体附件

创建推文或发送私信时直接附加媒体；当前 API 文档没有独立媒体上传路径。创建推文的 media_urls 支持最多四张图片，或一个 GIF，或一个视频。GIF/视频不能与其他媒体混用。遇到 URL 无法访问、格式不支持或文件过大时，先修正媒体，再重试。字段与约束以接口 Schema 为准。

私信

POST /v3/twitter/send-dm · /v3/twitter/dm-history · /v3/twitter/conversations

检查私信权限使用 POST /v2/dm/status。参阅 发送私信。

读取数据

POST /v2/tweet/detail · /twitter/tweets/lookup · /twitter/users/by_ids · /v3/twitter/users/followers · /v3/twitter/users/following · /twitter/tweets/thread_by_id · /twitter/tweets/{tweet_id}/replies/page

GET /twitter/{screen_name}/about · /twitter/search-user/{keyword}/{target_count}

文章

POST /x/article · GET /x/article/{tweet_id}/markdown

写接口：POST /x/articles/draft · PUT /x/articles/{article_id}/cover · /x/articles/{article_id}/title · /x/articles/{article_id}/content · POST /x/articles/{article_id}/publish 或 /x/articles/publish。

下表的 Premium 要求适用于发布文章。优先使用 分步发布流程，保存 article_id，仅重试失败步骤。

重试指南

建议： 对 429 和临时 5xx 使用带随机抖动、有次数上限的退避策略。对于 400/401/403/404/409/422，先修正输入、凭据或账号权限。

Twitter API 错误码与重试常见问题

Twitter API 为什么返回 401 或 invalid auth_token？

HTTP 401 可能表示 TwexAPI API Key 缺失或无效。写接口的 Invalid auth_token 或 X 错误码 32 也可能表示 X 会话已过期。先修正 Bearer 请求头，或更新通过 cookie 提交的 X 凭据，再重试。

Twitter API 错误 403 和 429 有什么区别？

HTTP 403 表示访问问题，例如额度不足、内容私密、账号受限或操作需要 Premium。HTTP 429 表示请求或账号触发限额。遇到 403 应修正访问条件；遇到 429 应等待对应限额恢复。

Twitter API 429 Too Many Requests 怎么解决？

如果响应提供 Retry-After 或 retry_after，先等待指定时间，再降低并发并使用有上限的退避策略。每日发推或私信限额需要等待重置，短暂延迟未必有效。读取分页数据时，保留并重试失败页的同一游标。

Twitter 错误码 187 是什么意思？

X 错误码 187 表示推文内容重复。先检查此前的写操作是否已经发布了推文。如果确实要发另一条推文，应修改 tweet_content，不要重复相同请求。

Twitter 错误码 344 是什么意思？

X 错误码 344 表示与网络或 IP 相关的临时发推限制。退避等待，检查你提供的代理，并在重试写操作前查看账号时间线。它属于 X 错误码，与 HTTP 状态码的含义不同。

Twitter API 返回 500、502 或 503 时应该重试吗？

临时读取错误可以采用有上限、带随机抖动的退避策略重试。写操作超时或返回 5xx 后，应先查询时间线、私信历史或互动状态。响应失败不能证明写操作没有执行。

TwexAPI 的 422 参数校验错误应该重试吗？

不要使用相同输入重试。TwexAPI 的 HTTP 422 表示请求参数校验失败。检查 detail 中的字段、位置和类型，再根据接口 Schema 修正请求。

Twitter 错误码 502 与 HTTP 502 是一回事吗？

不是。X 错误码 502 表示每日私信请求限额，可能随 HTTP 429 返回。HTTP 502 表示上游响应失败。选择重试策略前，应同时检查 HTTP 状态码与响应提供的 twitter_error_code。

相关页面

• 错误处理 — MCP、SDK 和分页恢复
• 身份认证 — API Key 与 X 会话凭据
• 速率限制 — 退避和吞吐控制
• API 概览 — 当前接口文档