Twitter/X Error 403: "Forbidden" (Tier Access & Scopes)

The Diagnosis: The "Pay-to-Play" Era of X

Since the transition from Twitter to X, the 403 Forbidden error has become the most common hurdle for developers. Unlike the old days of the platform where a 403 usually meant a simple coding error, today it is almost always a Business Logic or Billing error.

When you see this in your logs:

{"title": "Forbidden", "type": "about:blank", "status": 403, "detail": "Forbidden"}

It is Meta-data for one of three specific infrastructure shifts:

• The Tier Trap (Free vs. Basic vs. Pro): You are attempting to use a v2 endpoint (like POST /2/tweets) that your current subscription tier doesn't support. For example, the "Free" tier allows for very limited write-only access, while the "Basic" tier has a hard cap of 1,500 tweets per month.
• App Permissions (Read/Write): By default, many new X apps are set to "Read-only." If you attempt to post a tweet without changing your app settings in the X Developer Portal to "Read and Write," you will receive a 403.
• The V1.1 vs. V2 Conflict: If you are using a library that still points to the deprecated v1.1 endpoints but your API key is only authorized for v2, the platform will return a 403 Forbidden.

The Manual Fix: Navigating the X Developer Portal

To resolve a 403 error natively, you must audit your account standing and your code's endpoint targets.

1. Check App Settings

Log into the X Developer Portal. Navigate to your App Settings and find User authentication settings. Ensure that App permissions is set to "Read and write." If you change this, you must regenerate your Access Tokens, as old tokens will not inherit the new permissions.

2. Verify Monthly Usage

If your code was working yesterday but returns a 403 today, you have likely hit your monthly "Tweet Cap."

• Free Tier: 1,500 tweets per month (at the App level).
• Basic Tier: 3,000 tweets per month (shared across your user base). Once you hit 100%, the API shuts off with a 403 status until your billing cycle resets.

3. Endpoint Correction (Node.js)

Ensure you are targeting the correct version. If you are on a newer v2-only plan, your code must look like this:

// Using a library like twitter-api-v2const { TwitterApi } = require("twitter-api-v2");
const client = new TwitterApi({  appKey: "YOUR_APP_KEY",  appSecret: "YOUR_APP_SECRET",  accessToken: "USER_TOKEN",  accessSecret: "USER_SECRET",});
// TARGET V2 ENDPOINTasync function tweet() {  try {    const { data: createdTweet } = await client.v2.tweet("Hello world! This is a V2 tweet.");    console.log("Tweet ID:", createdTweet.id);  } catch (error) {    if (error.code === 403) {      console.error("Access Forbidden: Check your tier or app permissions.");    }  }}

For more detail, see Set Up Your Own X API Key.

The Ayrshare Solution: Enterprise-Grade Access

Ayrshare's infrastructure is built on Enterprise-level X API access. This means when you use Ayrshare, you are effectively "shielded" from the limitations of individual Basic or Pro tiers.

• No Monthly Caps for You: We manage the volume. You don't have to worry about your app shutting down mid-month because you hit 1,500 tweets.
• Pre-Configured Scopes: We handle the OAuth 2.0 flow with the correct tweet.read, tweet.write, and users.read scopes already baked in. No more regenerating tokens because a setting was missed.
• V1.1 to V2 Abstraction: We handle the complexity of which endpoint version to hit. You send a JSON body to /post, and we determine the most stable path to X's servers.

Comparison: Native vs. Ayrshare

For more detail, see X API documentation.

For more detail, see X (Twitter) API Error 429 (monthly tweet cap).

For more detail, see X Linking.