Twitter API Error Codes and HTTP Status Reference

Troubleshoot Twitter/X API errors in TwexAPI: HTTP 401, 403, 429 and 5xx, invalid auth_token, duplicate tweets, DM limits, and safe retries.

TwexAPI reports Twitter/X API failures through HTTP status codes and, when available, upstream X error codes. A 401 needs a credential fix, a 403 needs an access or account fix, and a 429 needs a rate-limit wait. Check the response body before retrying.

Use this reference to troubleshoot Twitter API error codes, invalid auth_token, duplicate tweets, and DM limits. Endpoint paths follow the current API reference. For MCP errors, pagination recovery, and SDK examples, see Error Handling.

Messages and upstream codes below are troubleshooting examples; response shapes and HTTP mappings can vary by endpoint. Use the endpoint schema and the actual response together.

Find the right Twitter API error fix

• HTTP 401 / Invalid auth_token: check both your TwexAPI API key and the X session credentials used by write endpoints. See Authentication.
• HTTP 403: inspect the message for insufficient credits, protected posts, account restrictions, or Premium requirements. Repeating an unchanged request does not restore access.
• HTTP 429 / Too Many Requests: honor Retry-After or retry_after, and distinguish request throttling from an X account’s daily limit. See Rate Limits.
• HTTP 500 / 502 / 503: retry transient read failures with capped backoff. Check whether a write already succeeded before repeating it.
• X codes 187, 344, or 502: these are upstream X codes, separate from HTTP status codes. Check the Twitter/X code table and the retry questions.

Error response format

Preserve the HTTP status and full JSON body. TwexAPI responses can include code and msg; request validation errors use detail:

{
  "code": 500,
  "msg": "Internal server error"
}

{
  "detail": [
    {
      "loc": ["body", "cookie"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

If the response includes additional upstream metadata, retain it:

• error: an error message, when supplied. Do not assume every endpoint uses this field.
• twitter_error_code: an X error code, when supplied. It is separate from the HTTP status; X code 502, for example, refers to a DM limit.
• retry_after: seconds to wait, when supplied. Also honor the HTTP Retry-After header.

Do not require optional fields to exist or branch only on exact message text. A non-2xx HTTP status is a failure even if the body contains a different code.

Common errors (all endpoints)

Check these conditions on any request. Exact messages can vary.

Twitter API HTTP status codes

Twitter/X API error codes

When an upstream X code is included in the response, use the following meanings. These are X codes, not HTTP statuses, and not every endpoint exposes twitter_error_code.

Reading tweets & search

Applies to POST /twitter/{screen_name}/timeline/page, /twitter/tweets-replies/page, and /twitter/advanced_search/page.

Posting & engagement

Create Tweet

POST /twitter/tweets/create

Use tweet_content, optional reply_tweet_id, and your X credentials in cookie. See Create a Tweet or Reply.

Favorite / Retweet / Bookmark

POST /twitter/tweets/{tweet_id}/like · /twitter/tweets/{tweet_id}/retweet · /twitter/tweets/{tweet_id}/bookmark

DELETE /twitter/tweets/{tweet_id}/like · /twitter/tweets/{tweet_id}/retweet · /twitter/tweets/{tweet_id}/bookmark

Delete Tweet

POST /twitter/tweets/delete-batch

Supply target_id to delete one tweet. Omitting it selects bulk deletion; preserve the original request fields when recovering from errors.

Follow / Unfollow

POST /twitter/user/follow · DELETE /twitter/user/follow

Update Profile / Avatar / Banner

POST /twitter/profile

Use profile_image and profile_banner for image URLs, and cookie for X credentials.

Media attachments

Attach media when creating tweets or sending DMs; there is no separate media-upload route in the current reference. For tweet creation, media_urls supports up to four images, one GIF, or one video. Do not mix a GIF/video with other media. Fix inaccessible URLs, unsupported formats, or rejected file sizes before retrying. Follow the endpoint schema for field names and constraints.

Direct Messages

POST /v3/twitter/send-dm · /v3/twitter/dm-history · /v3/twitter/conversations

For permission checks, use POST /v2/dm/status. See Send DM.

Reading data

POST /v2/tweet/detail · /twitter/tweets/lookup · /twitter/users/by_ids · /v3/twitter/users/followers · /v3/twitter/users/following · /twitter/tweets/thread_by_id · /twitter/tweets/{tweet_id}/replies/page

GET /twitter/{screen_name}/about · /twitter/search-user/{keyword}/{target_count}

Articles

POST /x/article · GET /x/article/{tweet_id}/markdown

For writes: POST /x/articles/draft · PUT /x/articles/{article_id}/cover · /x/articles/{article_id}/title · /x/articles/{article_id}/content · POST /x/articles/{article_id}/publish or /x/articles/publish.

The Premium requirement below applies to publishing articles. Prefer the step-by-step article flow so you can preserve article_id and retry only the failed step.

Retry guide

Tip: Use capped backoff with jitter for 429 and transient 5xx. For 400/401/403/404/409/422, fix the input, credentials, or account access first.

Twitter API error and retry questions

Why does the Twitter API return 401 or invalid auth_token?

HTTP 401 can mean your TwexAPI API key is missing or invalid. On write endpoints, Invalid auth_token or X code 32 can also mean the X session has expired. Fix the Bearer header or refresh the X credentials supplied in cookie before retrying.

What is the difference between Twitter API errors 403 and 429?

HTTP 403 indicates an access problem, such as insufficient credits, private content, a restricted account, or a Premium-only action. HTTP 429 indicates a request or account limit. Fix the cause of a 403; wait for the indicated limit to reset after a 429.

How do I fix Twitter API 429 Too Many Requests?

Wait for Retry-After or retry_after when provided, then resume with lower concurrency and capped backoff. A daily tweet or DM limit needs its reset period, not just a short delay. Preserve the failed page’s cursor when retrying a read.

What does Twitter error code 187 mean?

X error code 187 means duplicate tweet content. Check whether the previous write already created the post. If you intend to publish a different post, change tweet_content instead of repeating the same request.

What does Twitter error code 344 mean?

X error code 344 indicates a temporary posting restriction associated with the network or IP. Back off, check any proxy you supplied, and inspect the account timeline before retrying the write. It is an X error code, not an HTTP status code.

Should I retry Twitter API errors 500, 502, or 503?

Retry transient read failures with capped backoff and jitter. After a write times out or returns 5xx, first inspect the timeline, DM history, or engagement state. A failed response does not prove that the write was never applied.

Should I retry a TwexAPI 422 validation error?

Do not retry the same input. TwexAPI uses HTTP 422 for request validation errors. Inspect detail for the failing field, location, and type, then correct the request according to the endpoint schema.

Is Twitter error code 502 the same as HTTP 502?

No. X error code 502 refers to a daily DM request limit and can accompany HTTP 429. HTTP 502 indicates an upstream response failure. Read both the HTTP status and twitter_error_code, when provided, before choosing a retry policy.

Related pages

• Error Handling — MCP, SDKs, and pagination recovery
• Authentication — API keys and X session credentials
• Rate Limits — backoff and throughput
• API Overview — current endpoint reference