Error reference

X API errors and troubleshooting

Map X API errors for invalid credentials, usage caps, duplicate posts, blocked URLs, account restrictions, and video length limits. Use this reference to choose between reconnecting X, changing post copy, trimming media, or waiting for rate and usage limits to reset.

Last updated: May 2026

Open bundle.social docs

Error desk

12 mapped failures

unauthorized

Authentication

Reconnect
invalid credentials

Authentication

Reconnect
usage-capped

Rate Limiting

Retry later
usage cap

Rate Limiting

Retry later

12 documented error patterns across 4 categories

Clear guidance on reconnecting, retrying, replacing media, or changing content

Official platform references plus bundle.social production troubleshooting notes

Error categories

Find the failure type first

12 documented errors

Authentication

2 errors

Rate Limiting

2 errors

Content

5 errors

Video

3 errors

All error codes

Codes, causes, and fixes

Authentication

2 mapped cases

Authentication
unauthorizedReconnect

X rejected the connected account credentials.

Reconnect X and create fresh credentials for the user.

refresh-token
invalid credentialsReconnect

The X credentials are expired or invalid.

Reconnect the account after password changes or revoked app access.

refresh-token

Rate Limiting

2 mapped cases

Rate Limiting
usage-cappedRetry later

The account or app hit an X usage cap.

Wait for reset or reduce posting frequency for that account tier.

retry
usage capRetry later

X blocked the request because the usage cap was reached.

Retry after the cap resets and avoid sending bursts.

retry

Content

5 mapped cases

Content
duplicateFix input

X detected recently posted duplicate content.

Change the text or media, or wait before publishing similar content.

user-error
you have already posted thisFix input

The exact post was already published recently.

Make the post meaningfully unique before retrying.

user-error
duplicate-rulesRetry later

X duplicate rules blocked a repeat post.

Delay retries for 30 to 60 minutes and avoid identical content.

retry
invalid urlFix input

The post includes a URL that X does not allow.

Remove the URL, replace the domain, or avoid blocked link shorteners.

user-error
The Tweet contains an invalid URLFix input

X rejected a URL in the post.

Use a reputable destination URL or publish without the link.

user-error

Video

3 mapped cases

Video
video longer than 2 minutesFix input

The account cannot publish a video of this length.

Trim the video or use an account tier that supports longer uploads.

user-error
video lengthFix input

The video duration exceeds the account limit.

Match the video length to the account subscription tier.

user-error
This user is not allowed to post a video longer than 2 minutesFix input

X blocked long video publishing for this user.

Shorten the video below the user's allowed limit before retrying.

user-error

Unauthorized or expired token

X returns 401 when credentials are missing, expired, regenerated, or signed with the wrong authentication method.

Rate limit exceeded

X publishes rate limit headers that show the limit, remaining requests, and reset time. Respect those headers instead of retrying immediately.

X errors depend heavily on API tier and account limits

A request can fail even with valid credentials when the app does not have access to the endpoint, the account hits usage caps, the post is duplicated, the URL is blocked, or the media exceeds account-level limits.

Duplicate posts and usage caps should not be retried immediately

If X rejects a post as duplicate content or usage-capped, immediate retries usually create more failures. Change the post text or media, or wait for the relevant usage window to reset.

How bundle.social helps

bundle.social groups X publishing failures by credentials, endpoint access, usage caps, duplicate rules, URL validation, video limits, and account restrictions so each failed post gets a practical next step.

Retry safety

Retry only temporary platform failures, processing delays, timeouts, 5xx responses, and rate-limit errors after the platform allows it. Do not retry the same request when the failure is caused by expired tokens, missing permissions, unsupported media, invalid captions, duplicate content, account restrictions, or policy blocks. The same payload will usually fail again until the account, media, content, or platform-specific setting is fixed.

Official references

Platform APIs change. Use these links to confirm current error behavior and field support.

bundle.social X API referenceX API response codes and errors

FAQ

Can X API error messages change over time?

X errors can vary by API tier, account state, endpoint access, media type, and usage caps. Read the error together with the account package, recent posts, media length, and rate-limit headers.

Should users reconnect the account for every failed post?

No. Reconnect X for invalid or revoked credentials. For duplicate content, invalid URLs, long videos, usage caps, or rate-limit responses, change the content or wait for the limit window first.

Does bundle.social hide the native platform error?

bundle.social keeps X's native error for support and highlights whether the next action is reconnecting, editing duplicate text, replacing media, or slowing down API requests.

Related

Keep researching

X API

Publishing and scheduling workflows for X.

Social media API

One API for publishing, scheduling, media, analytics, and account workflows.

Social media posting API

Create and schedule posts across multiple platforms.

Media upload API

Upload media once and reuse it in platform posts.

Build with less platform drag

Use one API for social publishing workflows

Create account