---
title: "Twitter API 错误码与 HTTP 状态码参考"
description: "排查 TwexAPI 的 Twitter/X API 错误：401 认证失败、403 访问受限、429 限流、invalid auth_token、重复推文、私信限额及安全重试。"
lastModified: "2026-10-08"
sidebar:
  label: "错误参考"
seo:
  title: "Twitter API 错误码：401、403、429 与重试指南"
search:
  tags: ["Twitter API 错误码", "X API 错误", "invalid auth_token", "429 限流", "twitter_error_code"]
---

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

本页帮助你排查 Twitter API 错误码、`invalid auth_token`、重复推文和私信限额。下列路径与当前 [API 文档](/zh/api-reference/overview) 保持一致。MCP 错误、分页恢复和 SDK 示例请参阅 [错误处理](/zh/guides/error-handling)。

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

## 快速定位 Twitter API 错误

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

## 错误响应格式

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

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

```json
{
  "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` 不同，也应视为失败。

## 所有接口的常见错误

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

| 状态码 | 消息 | 含义 | 处理方式 |
| --- | --- | --- | --- |
| **401** | `Invalid or missing API key` | API Key 缺失或无效 | 检查 `Authorization: Bearer <key>` 请求头 |
| **400** | `Missing required … param: <x>` | 必填字段或参数缺失、无效 | 修正请求 |
| **429** | `Please try again shortly.`、`Rate limit exceeded…` 或 X 限额消息 | 请求过多、临时容量不足或 X 账号达到每日发推/私信限额；可能包含 `twitter_error_code` | 遵守 `retry_after` / `Retry-After`，每日限额需要等待更久 |
| **403** | 余额耗尽或访问被拒绝 | 额度不足或账号权限受限 | 检查余额和账号权限 |
| **422** | 参数校验错误（`detail`） | 请求字段不符合 Schema | 修正 `detail` 指出的字段，不要原样重试 |
| **500** | `Internal server error` | 临时服务错误 | 稍后重试 |

:::warning
**两种 401。** API 层的 `401` 表示 **API Key** 有问题。发推、点赞、修改资料等写接口的 `401` 也可能表示通过 **`cookie` 提交的 X 会话凭据**无效或过期，消息可能为 `Invalid auth_token` 或 `Could not authenticate you`。此时需要更新 X 会话凭据，参阅 [身份认证](/zh/authentication#写操作鉴权与-byoc自带授权-cookie--token)。
:::

## Twitter API HTTP 状态码

| 状态码 | 含义 |
| --- | --- |
| **200** | 成功 |
| **202** | 如果接口返回此状态，表示已接受，操作仍待处理 |
| **400** | 请求不正确：参数缺失或无效、代理 URL 无效、媒体过大 |
| **401** | 未授权：API Key 无效，或 `auth_token` 无效、过期 |
| **403** | 额度不足、目标账号私密或被封禁、操作账号受限、权限不足或需要 Premium |
| **404** | 用户、推文或资源不存在 |
| **409** | 冲突，例如重复推文 |
| **410** | 资源不可用，检查响应体是否说明账号被封禁 |
| **422** | 参数校验失败，检查 `detail` 并修正输入 |
| **423** | 如果 X 返回此状态，表示账号锁定或需要验证 |
| **429** | 请求过多或触发限额 |
| **500 / 502 / 503** | 临时服务端或上游错误，可以按退避策略重试 |

## X（Twitter）错误码

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

| 错误码 | 含义 | 处理方式 |
| --- | --- | --- |
| **32** | 无法认证 | 更新通过 `cookie` 提交的 X 会话凭据 |
| **63** | 目标账号被封禁 | 使用可访问的账号，或等待访问恢复 |
| **64** | 操作账号被封禁 | 更换账号 |
| **131** | X 内部临时错误 | 重试 |
| **139** | 已点赞 | 确认当前状态，不要重复操作 |
| **144** | 找不到指定 ID 的推文 | 推文已删除，或 ID 不正确 |
| **187** | 重复推文 | 确认此前是否已发布；如果确实要发新推文，修改文本 |
| **226** | 请求被判断为自动化 | 重试时遵守下方写操作恢复规则 |
| **326** | 账号临时锁定 | 在 `x.com/account/access` 解锁后重试 |
| **327** | 已转推 | 确认当前状态，不要重复操作 |
| **344** | 发推暂时受限（网络/IP 限流） | 退避等待，检查所用代理，并在重试前确认写入结果 |
| **349** | 无法向该用户发送私信 | 对方不接受你的私信 |
| **399** | X 会话登录失败 | 检查 X 会话凭据 |
| **433** | 回复受限或需要 Premium | 推文限制了回复，或此操作需要 X Premium |
| **465** | 无法转推过期推文 | 推文太旧，无法转推 |
| **476** | 不允许发送私信请求 | 当前账号无法发送私信请求 |
| **502** | 达到每日私信请求限额 | 等待 24 小时，或使用限额更高的 X Premium 账号 |

## 读取推文与搜索

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

| 状态码 | 消息 | 处理方式 |
| --- | --- | --- |
| **403** | `This account's posts are not available. The account is protected (private), suspended, or no longer active.` | **不要原样重试**。需要先恢复访问权限；私密账号的推文仅批准的关注者可读，改为查询公开账号 |
| **403** | `This account is suspended, so its posts are not available.` | 目标账号被封禁，使用可访问的账号或等待访问恢复 |
| **502** | `Upstream returned an unexpected response — please retry.` | 上游错误，**按有上限的退避策略重试**，保留同一分页游标 |

:::info
目标账号私密或被封禁导致的 `403`，需要改变访问权限或目标账号。`502` 可能是临时错误。请先检查状态码和响应体，再选择重试策略。
:::

## 发推与互动

### 创建推文

**POST** `/twitter/tweets/create`

提交 `tweet_content`，回复时提供 `reply_tweet_id`，并通过 `cookie` 提交 X 凭据。参阅 [创建推文或回复](/zh/api-reference/tweet-actions-endpoints/create-tweet-twitter-tweets-create-post)。

| 状态码 | X 错误码 | 消息 | 处理方式 |
| --- | --- | --- | --- |
| **409** | 187 | `Status is a duplicate.` | 检查推文是否已发布；发新推文时修改文本 |
| **403** | 433 | `The original Tweet author restricted who can reply…` | 原推文不允许你回复 |
| **403** | 433 | 长文或长视频需要 Premium | 使用 Premium 账号，或缩短内容 |
| **403** | n/a | 不是社区成员 | 先在 X 上加入社区 |
| **429** | 344 | 发推暂时受限（网络/IP 限流） | 退避等待，检查代理并确认是否已发布 |
| **502** | n/a | `X returned an empty result`（结果未确认） | 重试前读取账号时间线，确认写入结果 |
| **400** | n/a | `File size exceeds…` | 减小媒体文件 |
| **503** | 226 | `This request looks automated` | 退避等待，并在重试前检查写入结果 |
| **502 / 503** | n/a | 临时连接错误 | 重试前确认写入结果；若使用 `proxy`，检查代理是否正常 |

### 点赞 / 转推 / 收藏

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

| 状态码 | X 错误码 | 消息 | 处理方式 |
| --- | --- | --- | --- |
| **403** | n/a | `User is suspended, deactivated or offboarded` | 账号不可用，切换账号 |
| **401** | 32 | `Could not authenticate you` | 更新通过 `cookie` 提交的 X 会话凭据 |
| **403** | 465 | `not permitted to retweet an outdated Tweet` | 推文太旧，无法转推 |
| 依接口而定 | 139 / 327 | 已点赞 / 已转推 | 确认当前状态，不要重复操作 |
| **429** | n/a | 触发限额 | 降低频率，稍后重试 |
| **502 / 503** | n/a | 临时连接错误 | 确认当前状态后再重试 |

### 删除推文

**POST** `/twitter/tweets/delete-batch`

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

| 状态码 | 消息 | 处理方式 |
| --- | --- | --- |
| **404** | `No status found with that ID` | 已删除或 ID 不正确 |
| **403** | 不是作者 | 只能删除自己的推文 |
| **401** | `auth_token` 无效 | 更新 X 会话凭据 |

### 关注 / 取消关注

**POST** `/twitter/user/follow` · **DELETE** `/twitter/user/follow`

| 状态码 | 消息 | 处理方式 |
| --- | --- | --- |
| **404** | `User not found` | 检查用户名或 ID |
| **403** | 操作受限 | 当前账号或目标账号不允许此操作 |
| **401** | `auth_token` 无效 | 更新 X 会话凭据 |
| **429** | 关注限额 | 等待后再重试 |

### 更新资料 / 头像 / 横幅

**POST** `/twitter/profile`

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

| 状态码 | 消息 | 处理方式 |
| --- | --- | --- |
| **401** | `Invalid auth_token - could not fetch credentials` | 更新 X 会话凭据 |
| **400** | 图片过大或格式错误 | 修正图片 |

## 媒体附件

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

## 私信

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

检查私信权限使用 **POST** `/v2/dm/status`。参阅 [发送私信](/zh/api-reference/dm-endpoints/send-dm-api-v3-v3-twitter-send-dm-post)。

| 状态码 | X 错误码 | 消息 | 处理方式 |
| --- | --- | --- | --- |
| **429** | 502 | `You've hit your daily message request limit. Subscribe to Premium for higher limits.` | 等待 24 小时，或使用 Premium 账号 |
| **403** | 476 | `Sender is not verified to send message requests` | 当前账号无法发送私信请求 |
| **403** | 349 | `Cannot send messages to this user` | 对方不接受你的私信 |
| **401** | 32 | `Could not authenticate you` | 更新 X 会话凭据 |
| **404** | n/a | 会话或用户不存在 | 检查接收方 |

## 读取数据

**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}`

| 状态码 | 消息 | 处理方式 |
| --- | --- | --- |
| **404** | `Tweet not found: <id>` | 推文被删除、受保护或 ID 不正确 |
| **404** | `Could not resolve userId for @<handle>` | 用户名不存在、已改名或账号被封禁 |
| **404** | `Could not find user with ID: <id>` | 检查用户 ID |
| **400** | `Missing required query param: <x>` | 提供必填参数 |
| **429** | 触发限额 | 遵守 `retry_after` / `Retry-After` 后重试 |

:::info
**地区受限内容。** X 的访问限制可能取决于所在地区，包括你提供的代理的出口地区。请检查实际响应与目标内容的可访问性，不要假定 API 可以绕过地区限制。
:::

## 文章

**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 要求适用于发布文章。优先使用 [分步发布流程](/zh/api-reference/article-endpoints/article-create-draft-x-articles-draft-post)，保存 `article_id`，仅重试失败步骤。

| 状态码 | 消息 | 处理方式 |
| --- | --- | --- |
| **403** | 需要 Premium | 发布文章需要 X Premium 账号 |
| **404** | 文章不存在 | 检查文章 ID |
| **401** | `auth_token` 无效 | 更新 X 会话凭据 |
| **400** | 内容无效 | 修正文章正文 |

## 重试指南

| 遇到的情况 | 是否重试 | 说明 |
| --- | --- | --- |
| **429** | ✅ 等待指定时间后 | 同时遵守每日账号限额与请求速率限制 |
| **422** | ❌ | 修正校验响应中指出的字段 |
| **500 / 502 / 503** | ✅ | 临时错误，退避后重试 |
| **X 错误码 226** | 检查写入结果后再判断 | 退避等待，并检查账号限制 |
| **401** | ❌ | 修正 API Key 或更新 X 会话凭据 |
| **403**（封禁/锁定） | ❌ | 更换账号或先解锁 |
| **404** | ❌ | 检查 ID 或用户名 |
| **400 / 409** | ❌ | 修正参数、媒体大小或重复文本 |

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

:::warning 写操作重试
写操作超时、返回空响应或 `5xx` 后，先查询时间线、私信历史或互动状态，再决定是否重发。响应失败不代表操作一定没有执行。
:::

## 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`。

## 相关页面

- [错误处理](/zh/guides/error-handling) — MCP、SDK 和分页恢复
- [身份认证](/zh/authentication) — API Key 与 X 会话凭据
- [速率限制](/zh/guides/rate-limits) — 退避和吞吐控制
- [API 概览](/zh/api-reference/overview) — 当前接口文档