WEIR
获取 API Key
语言English日本語
主题

推特 API 错误码：X API 报错 401、403、429 怎么处理

推特 API 错误码速查：X API 报错 400、401、402、403、404、429、503 各是什么意思，哪些能重试，怎么退避，Tweepy 抛什么异常，还有一个无限重试的坑。


发布于 · 更新于 · 阅读约 7 分钟 · Read in English

封面图：重试，还是先修好？

推特 API 错误码就是标准的 HTTP 状态码：大多数 4xx 要你改请求，429 和 5xx 等一会儿再试。

这篇写给用 X（推特）API 读公开数据的开发者，不管你是自己发请求还是用 Tweepy。你会看到读数据时常见的每个状态码、怎么修，以及重试有没有用。

先把这条规则放进你的客户端：

RETRY = {429, 500, 502, 503, 504}

def should_retry(status: int) -> bool:
    """只重试速率限制和 X 自己的故障，其他的都要修。"""
    return status in RETRY
15 分钟X 最常见的速率限制窗口
3 个每个响应都带的速率限制响应头
$0X 对失败请求收的钱

推特 API 错误码速查表

截至 2026 年 10 月，读数据时可能遇到的状态码都在这里。含义来自 X 的响应码页，异常类名来自 Tweepy 4.17.0：

状态码 含义 Tweepy 抛出 能重试吗
400 请求格式错误 BadRequest 不能，先修
401 认证无效或缺失 Unauthorized 不能
402 积分用完 HTTPException 不能，先充值
403 没有权限 Forbidden 不能
404 已删除或不存在 NotFound 不能
429 速率限制或用量上限 TooManyRequests 等重置后
500、503 X 故障或过载 TwitterServerError 能，要退避

402 这一行最特别：X 自己的页面没有列出它，它来自开发者实际收到的报错。

400 修一次就好。错误里的 detail 字段会指出是哪个参数有问题。

X API 报错时，错误内容怎么看？

大多数错误，X 都用三个字段回答：type、title 和 detail。这是 X 文档里的例子：

{
  "title": "Invalid Request",
  "detail": "The 'query' parameter is required.",
  "type": "https://api.x.com/2/problems/invalid-request"
}

detail 说的是“缺少必填参数 query”。写代码时要按 type 分支。X 的文档列出的类型包括：

  • invalid-request：请求格式错误或参数无效。
  • resource-not-found：推文或用户不存在。
  • not-authorized-for-resource：私密或受保护的内容。
  • client-forbidden：应用没有加入相应计划，或缺少权限。
  • usage-capped 和 rate-limit-exceeded：都跟着 429 出现。

有个坑会让很多脚本中招。一次请求多条推文时，如果有几条已经没了，X 可能返回 200，同时带着 data 和 errors 数组。所以成功的响应也要检查 errors。

X API 报 401 和 403 有什么区别？

401 是 X 不知道你是谁。403 是 X 知道你是谁，但不给你这个。

X 的响应码页说，401 是“认证凭据无效或缺失”。先检查 Authorization: Bearer 请求头的格式，再确认密钥没有重新生成过。

搜 403 的人很多是在发推时遇到的。这里只讲读数据，因为 Weir 只读。读数据时，X 的文档列了四个原因：

  • 应用没有权限，调不了这个接口。
  • 接口要先申请，加入或获批之后才能用。
  • 缺少 OAuth 权限范围：用户身份的调用要带上对应的 scope。
  • 内容是私密的，或者来自受保护的账号。

同样的请求重试，还是 403。要换令牌、换权限范围，或者换目标。

X API 429 是什么意思？

429 表示你在当前窗口里请求太多，或者碰到了用量上限。

X 按接口计数，窗口通常是 15 分钟或 24 小时。每个接口有自己的额度：

应用令牌每 15 分钟能发的读取请求
用户推文时间线10,000
推文批量查询3,500
最近搜索450
按用户名查用户300
点赞用户列表75

这些数字来自 X 的速率限制页，2026 年 10 月 26 日核对。用户令牌的数字不同，完整的表见推特 API 速率限制。

每个响应都带三个响应头。x-rate-limit-limit 是窗口允许的最多请求数，x-rate-limit-remaining 是还剩几次。x-rate-limit-reset 是窗口重置的时间，格式是 Unix 时间戳。

正确做法是等到重置再试。重试次数要有上限，因为用量上限不会在下一个窗口解除：

import time, requests

def get_with_backoff(url, headers, tries=5):
    for attempt in range(tries):
        r = requests.get(url, headers=headers, timeout=30)
        if r.status_code == 429:
            reset = int(r.headers.get("x-rate-limit-reset", time.time() + 60))
            time.sleep(max(reset - time.time(), 1))
        elif r.status_code >= 500:
            time.sleep(2**attempt)
        else:
            return r
    return r

X API 402 又是什么意思？

402 Payment Required 表示你按量计费的积分用完了。X 的文档说，买更多积分之前，请求会一直失败，所以重试循环永远停不下来。

原因和修法见我们的 X API 402 错误指南。每读一条推文 $0.005，钱花在哪里见推特 API 价格 2026。

503 Service Unavailable 和其他 5xx 错误

5xx 是 X 的问题，不是你的。

X 的页面说，503 表示“X 过载了，等一下再试”。500 也是等一下再试，还附上了 X 状态页的链接。502 和 504 的建议一样：等，然后重试。

像上面的代码那样，用越来越长的间隔退避，并限制次数。如果错误一直不消失，先看 X 的 API 状态页，再考虑改代码。

Tweepy 怎么处理 X API 报错？

Tweepy 给常见的状态码各定义了一个异常类，都继承自 tweepy.HTTPException。每个异常都保留原始的 response，所以你可以把 X 的 detail 记进日志。

正因为都继承自同一个基类，捕获顺序很重要。先捕获 TooManyRequests，再捕获 HTTPException，否则通用的处理会吞掉你的限速逻辑。

Tweepy 也能替你等。开了 wait_on_rate_limit=True，客户端会睡到 x-rate-limit-reset 再重试 429。不开的话，TooManyRequests 带着一个 reset_time，你可以自己读。

Weir 的每个错误都告诉你能不能重试

Weir 是我们做的只读 API，读公开的 X 和 Reddit 数据，读这一节时请记住这一点。它的错误都是同一个格式，带一个可以直接判断的 retryable 字段。

2026 年 10 月 21 日，我们向 Weir 查询一个不存在的 X 账号，它返回 404 和下面的内容：

{
  "error": {
    "code": "not_found",
    "message": "X user not found.",
    "retryable": false
  }
}

这次调用没有扣积分。在 Weir 上，失败的调用都不收钱：

  • 429 带着 Retry-After，告诉你等几秒后同样的请求就能成功。
  • 402 表示积分用完。买一个套餐，或者等下个月的免费积分到账，它就解除。
  • 503 表示某个平台暂时连不上，带退避重试就行。

每个状态码和错误码都列在 Weir 错误文档（英文）里。

什么时候不适合用 Weir

  • 你要发推、点赞或关注。Weir 只读，写操作要用 X 自己的 API。
  • 需要和 X 本身签合同，或者每月要读 300 万条以上推文，得上企业版。
  • 读的是你自己的账号。X 对自有读取每条只收 $0.001。
  • 单价是唯一的标准。TwitterAPI.io 标价每千条推文 $0.15，比我们的小套餐便宜。

Weir 和 X 没有关联，访问方式可能变化。两者每千条推文的价格对比见推特 API 替代方案。

常见问题

推特 API 最常见的报错是哪个？

读数据时，大多数脚本最先遇到的是 429 速率限制。它也最好处理：读 x-rate-limit-reset，睡到那个时间，再重试。其他 4xx 都需要你改点什么。

X API 的 429 会持续多久？

到 x-rate-limit-reset 标出的窗口结束为止。X 的窗口通常是 15 分钟或 24 小时，看接口。用量上限导致的 429 持续得更久，所以要限制重试次数。

X API 请求失败会扣积分吗？

不会。X 的用量和计费页说，只有返回了数据的成功响应才计费。报错不花钱，但会花你的时间，所以遇到不会自己消失的状态码就停下。

Tweepy 为什么抛 HTTPException，而不是具体的错误？

Tweepy 只给 400、401、403、404、429 和 5xx 定义了具体的类。其他状态码，比如 402 或 409，都抛基类 HTTPException。用 error.response.status_code 区分它们。

参考来源

以下均为英文页面：

继续阅读