WEIR
Get a key
Theme

X API Error Codes: What Each One Means and When to Retry

X API error codes decoded: what 400, 401, 402, 403, 404, 429 and 503 mean, which ones to retry, how to back off, and the Tweepy exception for each.


Published · Updated · 7 min read

Cover image: Retry it or fix it?

X API error codes are standard HTTP statuses: client errors mean you must change something, and server errors mean you wait and retry.

This page is for developers reading public data with the X API, by hand or through Tweepy. You get every common read-side code, its fix, and whether a retry can help.

Copy this rule into your client first:

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

def should_retry(status: int) -> bool:
    """Retry rate limits and X's own failures. Fix everything else."""
    return status in RETRY
15 minthe usual X rate limit window
3rate limit headers on each response
$0billed for a failed request on X

X API error codes at a glance

Here is every code you are likely to hit while reading data, as of October 2026. Causes come from X's response-codes page, and class names from Tweepy 4.17.0:

Code What it means Tweepy raises Retry?
400 Malformed request BadRequest No, fix it
401 Bad or missing auth Unauthorized No
402 Out of credits HTTPException No, top up
403 No permission Forbidden No
404 Deleted or never existed NotFound No
429 Rate limit or usage cap TooManyRequests After reset
500, 503 X failed or is overloaded TwitterServerError Yes, back off

The 402 row is the odd one out: X's own page doesn't list it, so it comes from the errors developers report.

Fix a 400 or 401 once and it stays fixed. The detail field names the bad parameter. For a 401, X's docs say to check whether your keys were regenerated.

How to read an X API error body

X answers most errors with three fields: type, title and detail. This example is from X's docs:

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

The type is the part to branch on. X's docs list these problem types, among others:

  • invalid-request is a malformed request or a bad parameter.
  • resource-not-found means the post or user doesn't exist.
  • not-authorized-for-resource is private or protected content.
  • client-forbidden says your app isn't enrolled or lacks access.
  • usage-capped and rate-limit-exceeded both come with a 429.

One trap catches many scripts. A request for several posts can return 200 with both data and an errors array, when some posts are gone. Always check for errors, even on success.

What does x api error 429 mean?

A 429 means you sent too many requests in the current window, or hit a usage cap.

X counts requests per endpoint, in windows that are usually 15 minutes or 24 hours. Each endpoint gets its own budget:

Read requests allowed per 15 minutes, app token
User posts timeline10,000
Post lookup, many ids3,500
Recent search450
User by username300
Liking users75

These come from X's rate-limits page as of October 2026. User tokens get different numbers.

Every response carries three headers that show where you stand. x-rate-limit-limit is the most requests the window allows, and x-rate-limit-remaining is how many you have left. x-rate-limit-reset is the moment the window resets, written as a Unix timestamp.

The right move is to wait until that reset, then try again. Bound the retries, because a usage cap won't clear at the next window:

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

Why do I get an x api 403 error?

A 403 means X knows who you are but won't let you have this. Many people who search for it are trying to post.

We only cover reading here, because Weir is read-only. For reads, X's docs point to four causes:

  • Your app lacks access to that endpoint.
  • The endpoint needs enrollment or approval first.
  • A user-context call is missing the right OAuth scope.
  • The content is private or from a protected account.

Retrying the same request returns the same 403. Change the token, the scope or the target.

What about x api 402?

A 402 Payment Required means your pay-per-use credits are gone. X's docs say requests fail until you buy more, so a retry loop never ends.

We explain the causes and the fix in our guide to the X API 402 Payment Required error. Each post read costs $0.005, and our X API pricing guide shows where the money goes.

X API 503 Service Unavailable and other 5xx errors

A 5xx error is X's fault, not yours.

X's page says a 503 means "X is overloaded; wait and retry." For a 500 it adds a pointer to its status page. A 502 or 504 gets the same advice: wait, then retry.

Back off with growing gaps, as the code above does, and cap the attempts. If the errors last, check X's API status page before you change your code.

How Tweepy handles X API errors

Tweepy maps each common code to its own class, all built on tweepy.HTTPException. Each one keeps the raw response, so you can log X's detail text.

That order matters when you catch them. Catch TooManyRequests before HTTPException, or the general handler swallows your rate limit logic.

Tweepy can also wait for you. With wait_on_rate_limit=True, its client sleeps until x-rate-limit-reset and retries a 429. Without it, TooManyRequests carries a reset_time you can read yourself.

How Weir reports errors

We run Weir, a read-only API for public X and Reddit data, so read this with that in mind. Its errors use one shape, with a retryable flag you can branch on.

We asked Weir for an X account that doesn't exist on 21 October 2026. It returned a 404 with this body:

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

That call cost nothing. On Weir, every failed call is free:

  • A 429 carries Retry-After, the seconds to wait before the same call works.
  • A 402 means out of credits. It clears when you buy a pack or next month's free credits arrive.
  • A 503 means a platform was unreachable, and you retry with backoff.

The Weir errors guide lists every status and code.

When not to use Weir

  • You need to post, like or follow. Weir only reads, so writes need X's own API.
  • You need a contract with X itself, or Enterprise volume above 3 million posts a month.
  • You read your own account. X prices owned reads at $0.001 each.
  • Price per post is your only goal. TwitterAPI.io lists $0.15 per 1,000 tweets, below our smaller packs.

Weir is not affiliated with X, so access can change. See Weir vs the official X API for the full comparison.

FAQ

What is the most common X API error?

For reading data, the 429 rate limit is the one most scripts meet first. It is also the easiest to handle: read x-rate-limit-reset, sleep until that time, then retry. Every other 4xx needs a change from you.

How long does an X API 429 last?

Until the window in x-rate-limit-reset ends. X's windows are usually 15 minutes or 24 hours, depending on the endpoint. A 429 from a usage cap lasts longer, so cap your retries.

Does a failed X API request cost credits?

No. X's usage and billing page says only successful responses that return data are billed. Errors still count against your time and your patience, so stop on codes that won't clear.

Why does Tweepy raise HTTPException instead of a named error?

Tweepy only has named classes for 400, 401, 403, 404, 429 and 5xx. Any other code, such as 402 or 409, raises the base HTTPException. Check error.response.status_code to tell them apart.

Sources

Keep reading