X API errors
X API errors are easiest to debug when you start with the exact code or message, the HTTP status, and the category together. This guide covers the X API v2 failures developers most often encounter when publishing posts, grouped into authentication, rate limit, content, and media failures. For each error, it explains what the response means, why it likely happened, and what to change before retrying. The quick-reference table at the end collects all 12 documented errors so you can search by code, message, or status while debugging a failed post.
How to identify the failure from code, message, and HTTP status
Start with the HTTP status, then match the exact code or free-text message. A 401 response points to authentication: the stored token is no longer accepted, or credentials failed validation. A 429 response points to a rate limit: the account has reached its tier-based usage cap. A 403 response is broader and needs the message to distinguish content from media failures. Duplicate and invalid URL messages are content failures, while video duration messages are media failures tied to the account tier. Do not retry the same payload unchanged after a 403 or 429. First identify which of the four categories applies, change the thing that category controls, and only then resubmit.
Authentication errors: unauthorized and invalid credentials
The unauthorized error returns HTTP 401 and means the stored access token is no longer accepted. This commonly happens when the user revoked app access, changed their password, or tokens were invalidated during a security event. The fix is to run the OAuth 2.0 flow again so a fresh access and refresh token pair is issued, then retry the post. The invalid credentials error also returns HTTP 401, but it means credentials failed validation at the auth layer. This often follows rotating an OAuth app client secret or a forced re-grant. The fix is to reconnect the account so the stored token is signed under the current secret. If both errors appear, treat them as separate checks: unauthorized asks whether the token is still accepted, while invalid credentials asks whether the credentials themselves validate.
Rate limit errors: usage-capped and usage cap
The usage-capped error returns HTTP 429 and means the account hit the tier-based usage cap. X enforces monthly post quotas per access tier, including Free, Basic, Pro, and Enterprise. The usage cap error returns the same HTTP 429 status and means the tier quota has been reached; it describes the same constraint surfaced in different wording. In both cases, retrying immediately will not help. Wait for the cap to reset at the month boundary or rolling window, or upgrade the X API tier. Before resubmitting, check how many posts the account has already published in the current window so you do not hit the same cap again.
Content errors: duplicate, you have already posted this, duplicate-rules, invalid url, and The Tweet contains an invalid URL
The duplicate error returns HTTP 403 and means X rejected the post as a duplicate. This happens when identical text is posted from the same account within a short window, because X uses a sensitive duplicate detector to prevent automation. The you have already posted this message is the exact-text version of the same problem. The duplicate-rules error is related but distinct: it means spam prevention triggered on a near-duplicate, such as the same text posted across multiple accounts or in tight succession. To fix duplicate failures, change at least one word, add a unique element such as a timestamp or emoji, vary the text per account, stagger posting times, or wait about 30 minutes before resubmitting. The invalid url error returns HTTP 403 and means a URL in the post is blocked by X, often because X blacklists URL shorteners and domains with poor reputations. The Tweet contains an invalid URL message means the link domain has been associated with spam, phishing, or malware. To fix URL failures, drop the URL, switch to a different shortener, use the canonical unshortened URL, or use a link from a clean domain. Custom branded short links typically pass where generic shorteners do not.
Media errors: video longer than 2 minutes, video length, and This user is not allowed to post a video longer than 2 minutes
The video longer than 2 minutes message returns HTTP 403 and means the account tier does not allow videos over 2 minutes. Free X accounts cap video uploads at 2 minutes 20 seconds, while Premium raises the limit significantly. The video length error returns the same HTTP 403 status and means the video length exceeds the account tier maximum. The This user is not allowed to post a video longer than 2 minutes message means a free-tier user attempted a Premium-tier upload. In all three cases the fix is the same: trim the clip to fit the tier limit, or upgrade the account. After trimming, verify the exported file duration before resubmitting, because a clip that looks short enough in an editor can still exceed the limit after encoding.
Quick reference and failure matrix
Use the quick-reference table below to search all 12 documented errors by code, message, category, and HTTP status. The failure matrix that follows maps each error to its likely cause and concrete fix, keeping near-duplicate codes separate so you can tell exact duplicates from near-duplicates, and tier quota failures from credential failures. The worked examples show how to vary duplicate text, replace a blocked URL, and trim a video to meet tier limits. Refer to the titles of those examples when reviewing the fixes.
| Code or message | HTTP status | Category | What it means |
|---|---|---|---|
| unauthorized | 401 | Authentication | The stored access token is no longer accepted. |
| invalid credentials | 401 | Authentication | Credentials failed validation at the auth layer. |
| usage-capped | 429 | Rate limit | The account hit X's tier-based usage cap. |
| usage cap | 429 | Rate limit | Tier quota reached. |
| duplicate | 403 | Content | X rejected the post as a duplicate. |
| you have already posted this | 403 | Content | Exact-text duplicate detected. |
| duplicate-rules | 403 | Content | Spam prevention triggered on a near-duplicate. |
| invalid url | 403 | Content | A URL in the post is blocked by X. |
| The Tweet contains an invalid URL | 403 | Content | URL blacklisted by X reputation system. |
| video longer than 2 minutes | 403 | Media | Account tier does not allow videos over 2 minutes. |
| video length | 403 | Media | Video length exceeds the account tier's maximum. |
| This user is not allowed to post a video longer than 2 minutes | 403 | Media | Free-tier user attempted a Premium-tier upload. |
Documented source specifications; verify current tier limits against official X documentation before publication.
| Code or message | HTTP status | Likely cause | Concrete fix |
|---|---|---|---|
| unauthorized | 401 | User revoked app access, changed password, or tokens invalidated during a security event. | Run the OAuth 2.0 flow again to mint a fresh access and refresh token pair, then retry. |
| invalid credentials | 401 | OAuth app client secret rotated or forced re-grant occurred. | Reconnect the account so the stored token is signed by the current secret. |
| usage-capped | 429 | Monthly post quota for the access tier reached. | Wait for the cap to reset at the month boundary or upgrade the X API tier. |
| usage cap | 429 | Same tier quota constraint, surfaced in different wording. | Upgrade tier or wait until the rolling window resets. |
| duplicate | 403 | Identical text posted from the same account recently. | Change at least one word, add a unique element, or wait about 30 minutes. |
| you have already posted this | 403 | Exact-text duplicate within a short window. | Modify the text or wait before resubmitting. |
| duplicate-rules | 403 | Same text posted across multiple accounts or in tight succession. | Vary the text per account and stagger posting times. |
| invalid url | 403 | URL shortener or domain blacklisted by X. | Drop the URL, switch shorteners, or use the canonical unshortened URL. |
| The Tweet contains an invalid URL | 403 | Link domain associated with spam, phishing, or malware. | Use a link from a clean domain; custom branded short links typically pass. |
| video longer than 2 minutes | 403 | Free accounts cap video uploads at 2 minutes 20 seconds. | Trim the clip or upgrade the account to Premium. |
| video length | 403 | Video length exceeds the account tier maximum. | Trim the clip or upgrade the tier. |
| This user is not allowed to post a video longer than 2 minutes | 403 | Free-tier user attempted a Premium-tier upload. | Trim the clip or upgrade to Premium or higher. |
Documented source specifications; verify current tier limits against official X documentation before publication.
Frequently asked questions
How do I tell which X API error I hit?
Start with the HTTP status, then match the exact code or free-text message. A 401 points to authentication, a 429 points to a tier usage cap, and a 403 needs the message to distinguish duplicate or URL content failures from video-length media failures. Change the thing that category controls before retrying the same post.
What should I change after a duplicate error?
Change at least one word and add a unique element such as a timestamp or emoji, vary the text per account, stagger posting times, or wait about 30 minutes before resubmitting. Exact-text duplicates and near-duplicates across accounts are treated as separate cases, so keep the returned code or message in your logs.
How do I fix a blocked URL in a post?
Drop the URL, switch to a different shortener, use the canonical unshortened URL, or use a link from a clean domain. The Tweet contains an invalid URL indicates the domain itself has a poor reputation with X, so replacing only the shortener may not be enough.
How do I fix a video length error?
Trim the clip to fit the account tier limit and verify the exported file duration before resubmitting, or upgrade the account tier.