X API Error Codes Decoder
Paste any of the X API error codes you got back, from a 401 to a 402, 403 or 429, and see what it means, why it happened, the exact fix and whether retrying will help.
The three causes behind most X API errors
Most X API errors trace back to three things: an auth or permission problem (401 or 403, often a bad OAuth 1.0a signature or a Read only app), an empty pay-per-use balance (402 credits depleted), or a rate limit (429, retry after x-rate-limit-reset). Paste the response below to see which one you have.
Your diagnosis appears here: what the error means, likely causes, fix steps, whether a retry helps, and the rate-limit reset in your local time.
X API error codes at a glance
The status code tells you the class of problem; the type, title and detail fields in the body tell you which one. Error types below are from X's response codes reference.
| Status | Means | Retry? |
|---|---|---|
| 400 | Invalid JSON, malformed query, missing parameter | After fixing |
| 401 | Invalid or missing credentials | After fixing |
| 402 | Pay-per-use credits depleted | After top-up |
| 403 | Authenticated, but not allowed to do this | After fixing |
| 404 | Resource does not exist or was deleted | No |
| 429 | Rate limit or usage cap exceeded | After reset |
| 5xx | Problem on X's side | Yes, with backoff |
| Problem type | X describes it as |
|---|---|
| invalid-request | Malformed request or invalid parameters |
| resource-not-found | Post, user or other resource does not exist |
| not-authorized-for-resource | No access to private or protected content |
| client-forbidden | App not enrolled or lacks required access |
| usage-capped | Usage cap exceeded |
| rate-limit-exceeded | Rate limit exceeded |
| about:blank | Generic error, read the HTTP status |
402 is not in X's status table
X's response codes page does not list 402, but pay-per-use accounts receive it when credits run out. OpenTweet's own publisher sees it during credit outages and treats it as safe to retry once the balance is restored.OAuth 2.0: "You weren't able to give access to the App"
This screen appears on X before any API call, so there is no error body to paste. Work through this checklist, taken from X's OAuth 2.0 with PKCE docs.
- 1
Client ID and secret come from the same app
X's xurl troubleshooting guide lists a missing CLIENT_ID and CLIENT_SECRET as the cause of "Something went wrong. You weren't able to give access to the App". Copy both from the same app's keys and tokens page.
- 2
OAuth 2.0 is turned on for the app
X requires you to enable OAuth 2.0 in the app's authentication settings in the Developer Console before the authorize URL works.
- 3
The redirect_uri matches a registered callback exactly
X uses exact match validation. Protocol, host, port, path and any trailing slash must match one of the callback URLs on the app. URL-encode it in the authorize URL.
- 4
PKCE is complete
Send code_challenge and code_challenge_method (S256 or plain) in the authorize URL, then the matching code_verifier with code, grant_type, client_id and redirect_uri when you exchange the code.
- 5
The code is exchanged within 30 seconds
X says the authorization code expires 30 seconds after it is issued. Exchange it straight away in the callback handler.
- 6
offline.access is in the scope list
Without offline.access X issues no refresh token, and the access token stops working after two hours. Ask for tweet.read, tweet.write and users.read too if you post.
Tokens that worked and then stopped are a different problem. See how to fix an expired X OAuth refresh token.
Skip X auth and the X API bill
With OpenTweet you post through one ot_ API key. No developer app, no OAuth signing, no token refresh and no credit balance to watch. Send POST /api/v1/posts and the post goes out on your connected X account, or to Bluesky and LinkedIn too.
X's content rules still apply: duplicate text and replies you were not summoned to are refused the same way.
7-day free trial, then from $11.99/mo. API included on every plan. API docs
curl -X POST https://opentweet.io/api/v1/posts \
-H "Authorization: Bearer ot_your_key" \
-H "Content-Type: application/json" \
-d '{"text": "Shipped the fix.", "publish_now": true}'X API Error Codes FAQ
What are the most common X API error codes?
The ones developers hit most are 401 Unauthorized (often code 32 "Could not authenticate you"), 402 credits depleted on pay-per-use, 403 Forbidden in several variants (Read only app, duplicate content, replies you were not summoned to, app not enrolled), 429 Too Many Requests and 400 Invalid Request. Paste the response body into the decoder to see which one you have.
What does X API 402 credits depleted mean?
Your pay-per-use credit balance cannot cover the request. X says requests fail until you add credits, a balance that went slightly negative stays blocked until it is covered, and auto-recharge does not run at zero or below. Top up in the Developer Console. Some developers report a 402 while a balance shows, which is an open topic in the X developer forum.
What does client-not-enrolled mean on the X API?
The app exists but is not enrolled in the access the endpoint needs. X documents the client-forbidden type as "App not enrolled or lacks required access" and its troubleshooting table gives the fix: in the Developer Console move the app to the Pay-per-use package and the Production environment.
Why do I still get 403 oauth1-permissions after switching to Read and write?
Access tokens keep the permission level they were issued with. After you change the app to Read and write, regenerate the Access Token and Secret and replace the old pair everywhere. X notes that changing permissions requires users to re-authorize to get tokens with the new scope.
What does "Could not authenticate you" code 32 mean?
X could not verify the OAuth 1.0a signature on the request. Common causes are query parameters missing from the signature base string, signing with the wrong Content-Type, percent-encoding mistakes, or keys and tokens from different apps or regenerated since. A maintained OAuth library and a fresh set of four credentials fix most cases.
How do I know when an X API 429 resets?
Read the x-rate-limit-reset response header. It is a Unix timestamp in seconds for when the window resets. Wait until then, and add exponential backoff. Paste your headers into the decoder and it converts the timestamp to your local time with a countdown.
Should I retry an X API duplicate content error?
No. The same text gets the same 403 every time. Check the timeline first, because developers report the error appearing even when the first attempt published. If it did not publish, change the text.
Does this decoder send my error anywhere?
No. Parsing runs in your browser and nothing you paste leaves the page. Error bodies and rate-limit headers do not contain secrets, but remove any Authorization header before pasting headers anyway.
Can I post to X without my own X developer app?
Yes, through OpenTweet. Create an ot_ API key and send POST /api/v1/posts with Authorization: Bearer ot_... OpenTweet handles X auth, tokens and the X API bill. X's own content rules, such as duplicate content and the reply restriction, still apply. Plans start at $11.99/mo with a 7-day free trial.
Related tools and guides
X API Error Codes Reference
What 400, 401, 403, 429 and 187 mean when a post fails.
X API 403 Forbidden
The four causes of a 403 on POST /2/tweets and how to fix each.
X API 429 Rate Limits
How X rate limits work and how to back off.
Why Posting Returns 403
The short answer for POST /2/tweets 403 errors.
X API 429 Too Many Requests
What a 429 means and when to retry.
Fix the Reply Restriction
Replies since February 23, 2026 need the author to summon you.
Fix n8n Twitter 403
Get the n8n X node posting again.
X Character Counter
Weighted count for posts that fail as too long.
X API Cost Calculator
Price out a month on the pay-per-use meter.