X (Twitter) API Error ReferenceComplete troubleshooting guide with solutions

Comprehensive reference for X API errors. Find solutions and troubleshoot common integration issues.

12 error codes
4 categories
API v2

Error Categories

Authentication

2 errors

Rate Limiting

2 errors

Content

5 errors

Video

3 errors

All Error Codes

#Authentication

unauthorizedrefresh-token

X (Twitter) credentials are invalid. Please reconnect your account.

Solution:

Your X/Twitter credentials are no longer valid. This can happen after a password change or if you revoked app access. Reconnect your account in settings.

invalid credentialsrefresh-token

X (Twitter) credentials are invalid. Please reconnect your account.

Solution:

Your authentication credentials are incorrect or expired. Go to your account settings and reconnect your X/Twitter account.

#Rate Limiting

usage-cappedretry

X (Twitter) usage cap reached. Please try again later.

Solution:

You've reached X's usage limits for your account tier. Free accounts have lower limits. Wait for your quota to reset or upgrade to X Premium for higher limits.

usage capretry

X (Twitter) usage cap reached. Please try again later.

Solution:

X enforces usage caps based on your subscription tier. The cap typically resets every 24 hours. Consider upgrading to X Premium for higher limits.

#Content

duplicateuser-error

You have already posted this content. Please wait before posting again or modify your content.

Solution:

X prevents posting identical content too frequently. Wait at least 30 minutes before posting the same content, or modify your post slightly to make it unique.

you have already posted thisuser-error

You have already posted this content. Please wait before posting again or modify your content.

Solution:

You've posted this exact content recently. X's duplicate detection is very sensitive. Change your text, add different media, or wait before posting.

duplicate-rulesretry

You have already posted this post, please wait before posting again.

Solution:

Duplicate post detected. Wait at least 30-60 minutes before attempting to post similar content. This helps prevent spam on the platform.

invalid urluser-error

Your post contains a URL that is not allowed on X (Twitter).

Solution:

X blocks certain URLs that violate their policies. Remove the URL or use a different link. Avoid using link shorteners that X has blacklisted.

The Tweet contains an invalid URLuser-error

Your post contains a URL that is not allowed on X (Twitter).

Solution:

The URL in your post is blacklisted or considered spam. Use a different URL or remove the link entirely. Ensure the domain has a good reputation.

#Video

video longer than 2 minutesuser-error

Your account is not allowed to post videos longer than 2 minutes. Please upgrade to X Premium or shorten your video.

Solution:

Free X accounts are limited to 2-minute videos. Either: 1) Trim your video to under 2 minutes, or 2) Upgrade to X Premium/Premium+ for longer video support.

video lengthuser-error

Your account is not allowed to post videos longer than 2 minutes. Please upgrade to X Premium or shorten your video.

Solution:

Video length restrictions are based on your subscription tier. Free: 2min, Premium: 10min, Premium+: 120min. Upgrade or reduce your video length.

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

Your account is not allowed to post videos longer than 2 minutes. Please upgrade to X Premium or shorten your video.

Solution:

Your account tier doesn't support videos of this length. Upgrade to X Premium ($8/month) for 10-minute videos or Premium+ for 2-hour videos.

Best Practices

Error Handling

  • Implement automatic retries for rate limit and service errors
  • Store refresh tokens securely and handle token refresh flows
  • Log all errors with context for debugging
  • Show user-friendly error messages in your UI

Prevention Tips

  • Validate content before sending to X API
  • Compress videos and optimize media before upload
  • Implement rate limiting in your application
  • Follow X's Terms of Service and Community Guidelines

Need Help with X (Twitter) Integration?

Our API handles duplicate detection, rate limiting, and tier-based restrictions automatically.