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

X API 402 错误：CreditsDepleted 是什么意思，怎么解决

X API 402 错误 CreditsDepleted 表示按量计费的积分用完了。讲清为什么重试没用、怎么查余额和充值、免费积分何时过期，以及让脚本及时停下的写法。


发布于 · 更新于 · 阅读约 7 分钟 · Read in English · 日本語で読む

封面图：推特 API 为什么突然停了

X API 402 错误表示你的按量计费积分用完了，充值之前 X 会拦下所有请求。

这篇写给机器人或脚本突然停掉的开发者，不管你用的是 Tweepy、xurl，还是 AI 智能体里的 X 工具。你会看到原因、在开发者控制台里怎么修，以及遇到 402 就停、不再重试的代码。

先查余额，用的是 X API 文档里的这个接口：

curl "https://api.x.com/2/usage/credits" \
  -H "Authorization: Bearer $BEARER_TOKEN"

如果 total_balance 是 0，你的 402 就找到原因了。

402Payment Required：积分用完
$0余额到这里，自动充值就暂停
3 个月X 送的免费积分的有效期
$0.005每读一条推文，截至 2026 年 10 月

X API 402 错误 CreditsDepleted 是什么意思？

X API 按量计费：你先买积分，每读一条推文或一个账号，就从里面扣。X 的用量和计费页写得很直白：余额用完后，“API 请求会失败，直到你购买更多积分”。

奇怪的是，X 的文档从来没写过 402 本身。它的状态码页列了 400、401、403、404、409 和 429，接着就是 5xx 错误。

所以我们去看开发者实际收到了什么。2026 年 10 月 26 日，我们用 Weir 在 X 上搜 CreditsDepleted，最近的一条讨论发于 10 月 21 日。一位开发者贴出过完整的错误内容，删减后如下：

{
  "title": "CreditsDepleted",
  "detail": "Your enrolled account does not have any credits to fulfill this request."
}

detail 的意思是“你登记的账户没有积分来完成这个请求”。搜到的帖子里有英文、中文和日文，很多人是在用 xurl 或机器人发推时碰到的。

推特 API 的积分为什么用完了？

大多数 402 来自下面五个原因之一。截至 2026 年 10 月，这些都写在 X 自己的文档里：

  • 余额到 0 了。每读一条推文 $0.005，循环跑得快，钱也花得快。
  • 余额变成了负数。X 的价格页说这会发生，补上之前请求一直被拦。
  • 免费积分过期了。X 的新手积分 3 个月后失效，从余额里消失。
  • 一波请求跑赢了自动充值。自动充值每 5 分钟最多触发一次，快速的任务能把它甩在后面。
  • 自动充值暂停了。余额为 0 或负数时，它不会运行。

免费积分最容易坑人。X 的免费积分页写着：首次购买积分后送 $20，首次自动充值再送等额积分。

这个等额赠送最多 $50。免费积分还会先于你买的积分被花掉。一个靠它们跑了三个月的机器人，可能在过期当天就停了。

怎么解决 X API 402：在开发者控制台充值

解决办法就是充值，而且要人在 X 开发者控制台 console.x.com 里操作。

  1. 查余额调 GET /2/usage/credits，或在控制台打开 Billing 下的 Credits。
  2. 买积分没绑卡就先在 Billing information 里加卡，再买积分。
  3. 设自动充值选好 Recharge amount 和 Trigger threshold，防止下次再停。
  4. 设消费上限用 Spending limit 限制一个计费周期最多花多少。
  5. 重跑任务手动启动一次，盯着前几个响应。

X 的价格页说，余额归零后自动充值不会自己恢复，所以要手动充一次。

消费上限也有个坑。花到上限后，X 会拦下请求，直到下一个计费周期。X 没说这时返回哪个状态码，所以余额看着没问题时，也检查一下上限。

为什么重试 402 没有用？

402 不是超时：有人付钱之前，X 那边什么都不会变。

所以它和 429 速率限制（英文）正好相反。速率限制在窗口重置后就解除，等一等就好。空掉的余额不会自己补上，所以重试循环会一直转下去。

这些失败的调用不收钱。X 的用量和计费页说，只有返回了数据的成功响应才计费。但你的任务卡住了，日志也会被刷满。

Tweepy 报 402 Payment Required：捕获它，然后停下

Tweepy 没有 402 专用的异常类。它的源码给 400、401、403、404、429 和 5xx 各定义了异常，其他状态码都变成基类 tweepy.HTTPException。

错误信息是“402 Payment Required”加上 X 的说明文字，所以捕获它，然后退出：

import os, sys, tweepy

client = tweepy.Client(bearer_token=os.environ["X_BEARER_TOKEN"])
try:
    response = client.search_recent_tweets(query="python", max_results=10)
except tweepy.HTTPException as error:
    if error.response.status_code == 402:
        sys.exit("X API 积分用完了，请到开发者控制台充值。")
    raise

这里别指望 wait_on_rate_limit=True，Tweepy 的代码只在 429 时用它。

怎么防止脚本把积分烧光？

三个习惯，能防止一个任务一夜之间把账户掏空：

  • 大任务之前先查余额。读 total_balance，低于你定的下限就别跑。
  • 限制页数。每个循环都要有最大页数，不能写成“跑完为止”。
  • 设消费上限。你自己的代码出错时，它是最后一道闸。

页数上限为什么重要？最近搜索每次请求最多返回 100 条推文，每条 $0.005：

X API 上一个不设上限的搜索循环要花多少
10 页，每页 100 条$5
100 页$50
1,000 页$500

用 X API 费用计算器算算你自己的任务。这些数字背后的每个价格，见推特 API 价格 2026。还没有密钥的话，先看推特 API Key 怎么申请。

Weir 积分用完时会怎样？

Weir 是我们做的只读 API，读公开的 X 和 Reddit 数据，读这一节时请记住这一点。它也有 402，规则也一样：积分用完，不可重试。

不同的是，Weir 把它写进了文档。Weir 的 402 一定带着错误码 quota_exceeded 和 "retryable": false。买一个套餐，或者等下个月的免费积分到账，它就解除。

GET /v1/usage 不收费，积分用完时也照样能调：

curl --url https://api.weirapp.io/v1/usage \
  --header "Authorization: Bearer $WEIR_API_KEY"

2026 年 10 月 26 日，我们在自己的测试账号上跑了一次，返回的 data：

{
  "balance": 8654,
  "reserved": 0,
  "available": 8654,
  "freeGrant": {
    "granted": 5000,
    "remaining": 0,
    "resetsAt": "2026-11-01T00:00:00.000Z"
  },
  "tier": "free"
}

这个月的 5,000 免费积分已经用完，remaining 是 0。但账户里还有另外加进来的积分，所以调用照常进行。

每个计费的响应还带着 x-credits-remaining 响应头，脚本可以在归零之前就停下。每月 5,000 免费积分，不用绑卡，失败的调用不扣钱。每个状态码都列在 Weir 错误文档（英文）里。

在 Claude 或 Cherry Studio 里用 Weir 的话，get_usage 工具同样免费，可以直接问：“用 get_usage 看看我还剩多少积分，什么时候重置？”

什么时候不适合用 Weir

  • 你要发推、回复或发私信。Weir 只能读，写操作要用 X 自己的 API。
  • 你只读自己的账号。X 对自有数据每次读取收 $0.001，很难更便宜。
  • 你要和 X 本身签合同，比如每月超过 300 万条推文的 Enterprise 用量。
  • 你只看每条的价格。TwitterAPI.io 标价每千条推文 $0.15，比我们的小套餐便宜。

Weir 和 X 没有关联，访问方式可能变化。两者的完整对比见 Weir 和 X 官方 API 对比（英文）。

常见问题

X API error 402 是什么意思？

意思是你的 X API 按量计费余额不够这次请求。在开发者控制台充值之前，X 会拦下所有调用。X 的文档没有列出这个状态码，但错误里的 title 写着 CreditsDepleted，也就是积分已耗尽。

X API 失败的请求收费吗？

不收。X 的用量和计费页说，只有返回了数据的成功响应才计费。402 不花你的钱，但也什么都不返回，所以重试循环浪费的是时间，不是钱。

开了自动充值，为什么还会报 402？

有两个原因。自动充值每 5 分钟最多触发一次，一波请求可能先把充进来的钱花光。余额为 0 或负数时，它也会暂停，这时要手动充值才能让它重新运行。

X API 的免费积分会过期吗？

会。截至 2026 年 10 月，X 的免费积分页写明，新手积分发放 3 个月后过期，而且先于你买的积分被花掉。你自己买的积分不受影响。

参考来源

以下均为英文页面。

继续阅读