WEIR
Get a key
Theme

X API 402 Payment Required: What It Means and How to Fix It

An X API 402 Payment Required error means your pay-per-use credits ran out. Learn why retries fail, how to check your balance, and how to cap spend.


Published · Updated · 7 min read

Cover image: Why your X calls stopped

An X API 402 Payment Required error means your pay-per-use account is out of credits, so X blocks requests until you add more.

This guide is for developers whose bot or script just stopped, often inside Tweepy. You get the cause, the fix in the Developer Console, and code that stops instead of retrying.

Check your balance first, with this endpoint from X's API reference:

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

If total_balance comes back as 0, you have found your 402.

402Payment Required: no credits left
$0balance where auto-recharge pauses
3 monthsuntil X's free credits expire
$0.005per post read, as of October 2026

What an X API 402 Payment Required error means

The X API bills per use: you buy credits, and every post or profile you read is taken from them. When the balance runs dry, X's usage and billing page says it plainly: "API requests will fail until you purchase more credits."

The odd part is that X never documents the 402 itself. Its response-codes page lists 400, 401, 403, 404, 409 and 429, then the 5xx errors.

So we checked what developers actually see. We searched X with Weir on 21 October 2026 and found developers posting this error as recently as 18 October. In their logs, the title reads "Payment Required" and the detail reads "credits depleted".

Why your X API credits ran out

Most 402s come from one of five causes. All of them are in X's own docs, as of October 2026:

  • The balance hit zero. Every post read costs $0.005, and a busy loop spends fast.
  • The balance went negative. X's pricing page says this can happen, and requests stay blocked until you cover it.
  • Your free credits expired. X's starter credits last 3 months, then vanish from the balance.
  • A burst beat auto-recharge. It fires at most once every 5 minutes, so a fast job can outrun it.
  • Auto-recharge was paused. It does not run while the balance is zero or negative.

The free credits catch many people out. X's free-credits page offers $20 after your first credit purchase, plus a match of your first auto-recharge.

That match is capped at $50. Free credits are also spent before the ones you buy. A bot that lived on them for three months can stop the day they expire.

How to fix x api credits depleted in the Developer Console

The fix is a purchase, made by a person in the X Developer Console at console.x.com.

  1. Check the balanceCall GET /2/usage/credits, or open Billing → Credits in the console.
  2. Buy creditsAdd a card under Billing information if you have none, then buy credits.
  3. Set auto-rechargePick a Recharge amount and a Trigger threshold for next time.
  4. Set a Spending limitCap the most you can spend in one billing cycle.
  5. Rerun the jobStart it once, by hand, and watch the first responses.

X's pricing page says auto-recharge won't restart by itself after a zero balance, so you add credits by hand.

The spending limit has its own catch. When you reach it, X blocks requests until the next billing cycle. X doesn't say which status code that block returns, so check the limit too if your balance looks fine.

Why retrying a 402 does not help

A 402 is not a timeout: nothing changes on X's side until someone pays.

That makes it the opposite of a 429. A rate limit clears when its window resets, so waiting works. An empty balance never refills by itself, so a retry loop runs forever.

You won't pay for those failed calls. X's usage and billing page says only successful responses that return data are billed. But your job is stuck, and your logs fill up.

Tweepy 402 Payment Required: catch it and stop

Tweepy has no class for a 402. Its source raises named errors for 400, 401, 403, 404, 429 and 5xx, and anything else becomes the base tweepy.HTTPException.

The message reads "402 Payment Required" plus X's detail text, so catch it and exit:

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("Out of X API credits. Top up in the Developer Console.")
    raise

Don't lean on wait_on_rate_limit=True here, because Tweepy's code uses it only for 429s.

How to stop a script from burning credits

Three habits keep a job from draining your account overnight.

  • Check the balance before a big run. Read total_balance and stop below a floor you choose.
  • Cap the pages. Give every loop a maximum page count, never "until done".
  • Set a spending limit. It is the hard stop when your own code gets it wrong.

Here is why the page cap matters. Recent search returns up to 100 posts per request, and each post costs $0.005:

What an uncapped search loop costs on the X API
10 pages of 100 posts$5
100 pages$50
1,000 pages$500

Price your own job with the X API cost calculator. Every rate behind these numbers is in our X API pricing guide.

How Weir handles running out of credits

We run Weir, a read-only API for public X and Reddit data, so weigh this section knowing that. It has a 402 too, and it follows the same rule: out of credits, not retryable.

The difference is that Weir documents it. A Weir 402 always carries the code quota_exceeded and "retryable": false. It clears when you buy a pack or when next month's free credits arrive.

GET /v1/usage is free, and it still answers when you are out of credits:

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

We ran it on our own free account on 21 October 2026. The data it returned:

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

Every billed response also carries an x-credits-remaining header, so a script can stop before it hits zero. You get 5,000 free credits a month with no card, and a failed call costs nothing. The Weir errors guide lists every status.

When not to use Weir

  • You need to post, reply or send DMs. Weir only reads; writing needs X's own API.
  • You read your own account. X charges $0.001 per owned read, which is hard to beat.
  • You need a contract with X itself, such as Enterprise volume above 3 million posts a month.
  • Price per post is all that matters. TwitterAPI.io lists $0.15 per 1,000 tweets, below our smaller packs.

Weir is not affiliated with X, so access can change. Our Weir vs the official X API page compares the two in full.

FAQ

What does x api error 402 mean?

It means your X API pay-per-use balance can't cover the request. X blocks calls until you add credits in the Developer Console. X's docs don't list the code, but the error's own detail text reads "credits depleted".

Does the X API charge for failed requests?

No. X's usage and billing page says only successful responses that return data are billed. A 402 costs you nothing. It just returns nothing either, so a retry loop wastes time rather than money.

Why do I get a 402 when auto-recharge is on?

Two reasons. Auto-recharge fires at most once every 5 minutes, so a burst can drain a top-up first. It also pauses at a zero or negative balance. In that case, add credits by hand to restart it.

Do X API free credits expire?

Yes. X's starter credits expire 3 months after they are granted, and they are spent before purchased credits. Credits you buy are not affected, according to X's free-credits page, as of October 2026.

Sources

Keep reading