X API v2

X (Twitter) API Errors

Every common X (Twitter) API error developers hit when publishing — duplicate detection, tier caps, URL blocks, and more.

The X API surfaces errors in two shapes: machine-readable error codes for auth and rate limits, and free-text messages for content rejection. We've collected both.

PostPeer X (Twitter) API View Docs

Authentication2 Rate limit2 Content5 Media3

Authentication

2 errors in this category

unauthorizedHTTP 401Authentication

The stored access token is no longer accepted.

Why it happens: The user revoked app access, changed their password, or X invalidated tokens during a security event.
How to fix: Trigger the OAuth 2.0 flow again to mint a fresh access + refresh token pair.
How PostPeer handles it: PostPeer auto-refreshes X tokens before they expire. A surfaced "unauthorized" almost always means the user revoked access manually.

invalid credentialsHTTP 401Authentication

Credentials failed validation at the auth layer.

Why it happens: Common after rotating an OAuth app's client secret or after a forced re-grant.
How to fix: Reconnect the account so PostPeer can store a token signed by the current secret.

Rate limit

2 errors in this category

usage-cappedHTTP 429Rate limit

The account hit X's tier-based usage cap.

Why it happens: X enforces monthly post quotas per access tier (Free, Basic, Pro, Enterprise).
How to fix: Wait for the cap to reset at month boundary, or upgrade the X API tier.

usage capHTTP 429Rate limit

Tier quota reached.

Why it happens: Same constraint as `usage-capped`, surfaced differently.
How to fix: Upgrade tier or wait until the rolling window resets.

Content

5 errors in this category

duplicateHTTP 403Content

X rejected the post as a duplicate.

Why it happens: You posted identical text from the same account recently — X has a sensitive duplicate detector to prevent automation.
How to fix: Change at least one word, add a unique element (timestamp, emoji), or wait ~30 minutes.
How PostPeer handles it: PostPeer can be configured to append an invisible variation marker per post when you're posting from automation.

you have already posted thisHTTP 403Content

Exact-text duplicate detected.

Why it happens: X treats identical posts within a short window as automation abuse.
How to fix: Modify the text or wait before resubmitting.

duplicate-rulesHTTP 403Content

Spam prevention triggered on a near-duplicate.

Why it happens: Same text was posted across multiple accounts or in tight succession.
How to fix: Vary the text per account and stagger posting times.

invalid urlHTTP 403Content

A URL in the post is blocked by X.

Why it happens: X blacklists URL shorteners and domains with poor reputations to fight spam.
How to fix: Drop the URL, switch to a different shortener, or use the canonical (unshortened) URL.

The Tweet contains an invalid URLHTTP 403Content

URL blacklisted by X reputation system.

Why it happens: The link domain has been associated with spam, phishing, or malware.
How to fix: Use a link from a clean domain. Custom branded short links typically pass.

Media

3 errors in this category

video longer than 2 minutesHTTP 403Media

Account tier does not allow videos over 2 minutes.

Why it happens: Free X accounts cap video uploads at 2 minutes 20 seconds; Premium raises this significantly.
How to fix: Trim the clip or upgrade the account to Premium.

video lengthHTTP 403Media

Video length exceeds the account tier's maximum.

Why it happens: Same constraint as above.
How to fix: Trim or upgrade tier.

This user is not allowed to post a video longer than 2 minutesHTTP 403Media

Free-tier user attempted a Premium-tier upload.

Why it happens: Free accounts are explicitly capped at 2:20 video duration.
How to fix: Trim or upgrade to Premium ($8/mo) or higher.

Quick reference

All 12 X (Twitter) errors in one table — Ctrl/Cmd-F to find yours.

Code	Category	What it means
unauthorized	Authentication	The stored access token is no longer accepted.
invalid credentials	Authentication	Credentials failed validation at the auth layer.
usage-capped	Rate limit	The account hit X's tier-based usage cap.
usage cap	Rate limit	Tier quota reached.
duplicate	Content	X rejected the post as a duplicate.
you have already posted this	Content	Exact-text duplicate detected.
duplicate-rules	Content	Spam prevention triggered on a near-duplicate.
invalid url	Content	A URL in the post is blocked by X.
The Tweet contains an invalid URL	Content	URL blacklisted by X reputation system.
video longer than 2 minutes	Media	Account tier does not allow videos over 2 minutes.
video length	Media	Video length exceeds the account tier's maximum.
This user is not allowed to post a video longer than 2 minutes	Media	Free-tier user attempted a Premium-tier upload.

Other platforms

Instagram errors

33 documented

TikTok errors

25 documented

Facebook errors

15 documented

LinkedIn errors

9 documented

Bluesky errors

10 documented

Pinterest errors

8 documented

Threads errors

7 documented

YouTube errors

15 documented

Ready to Add Social Media to Your Product?

One API. Every platform. Start building with free credits.

Start Posting for FreeNo credit card required.

POST https://api.postpeer.dev/v1/posts
{ "platforms": ["twitter", "linkedin", "instagram], "content": "Hello world!" }

Published

5 platforms

TwitterLinkedInFacebook+2

All posts delivered

Scheduled

queue

Queued

847

Sent

Next: in 15 min

Platforms

connected

XIGFBLITT

One API, every platform