X API error handling for tweet & follower workflows

Choose recovery by error code.

Quick reference

Start with HTTP status. Retry only when stated.

400 request validation

Retry: no. Fix the body, query, or path. Examples include invalid_json, invalid_id, invalid_tweet_url, invalid_tweet_id.

401 authentication

Retry: no. Check x-api-key, regenerate revoked keys, or re-authenticate the connected X account. Covers unauthenticated and x_auth_failure.

402 billing and credits

Retry: no. Read payment_options, then get explicit user confirmation. Covers no_subscription, subscription_inactive, payment_failed, no_credits, and insufficient_credits.

403 permissions and account health

Retry: no. Delete an extra key, check billing status, use a participating DM account, re-authenticate the X account, or resolve account health on x.com. Covers api_key_limit_reached, dm_not_permitted, account_needs_reauth, and account_restricted. For x_account_protected, choose a public timeline.

404 missing resource

Retry: no. Verify the resource ID & connected account. Codes include account_not_found, user_not_found, tweet_not_found, no_media, and other missing resources.

409 or 410 cursor state

Busy cursor: follow Retry-After and retry once. Gone cursor: restart cursorless and deduplicate IDs.

422 write validation

Retry: no, except x_automation_refused. Fix the account capability, target, content, DM permissions, or media URL before sending again. Covers x_dm_not_allowed, x_reply_not_allowed, x_target_not_found, x_content_too_long, and the other 422 codes.

202 active write

Retry: no. Store the action and poll statusUrl while terminal is false. Follow Retry-After, pollAfterMs, and nextAction.

429 rate limit or cooldown

Retry: mixed. Retry rate_limit_exceeded and x_rate_limited after Retry-After or exponential backoff. Wait out login_cooldown via retryAfterMs. Do not retry x_daily_limit on the same X account for 24 hours.

500, 502, and 503 transient failures

Retry: yes for internal_error, x_api_rate_limited, x_api_unavailable and x_api_unauthorized. For writes, retry only when safeToRetry is true, using a new Idempotency-Key. Retry pagination_stalled once after 30 seconds. Keep returned results.

Common error codes

The OpenAPI Error schema lists every public code. Default response.

{ "error": "error_code", "message": "Human-readable description" }

Send xquik-api-contract: 2026-04-29 for a structured error object. Some responses also include message, reason, retryAfter, or retryAfterMs.

Validation errors (400)

Invalid body, query, or path.

invalid_input

Invalid body. Check the endpoint’s required fields, types & enum values.

invalid_json

Invalid JSON body. Send a parseable JSON object.

invalid_id

Invalid path ID. Use the create or list endpoint’s numeric string.

invalid_tweet_url

Tweet URL is malformed. Use https://x.com/user/status/ID.

invalid_tweet_id

Send a post ID or post URL, such as x.com/nasa/status/20.

invalid_username

Username is empty or invalid. Send a username without the @ prefix.

invalid_user_id

Send a user ID, @username or profile URL, such as x.com/nasa.

invalid_message_id

Send a DM ID from DM history.

account_required

Add your connected X account, such as ?account=@nasa.

invalid_tool_type

Unknown extraction tool type. Use one of the 23 types from Create Extraction.

invalid_format

Export format is unsupported. Use csv, json, md, md-document, pdf, txt, or xlsx.

invalid_params

Invalid export query. Check the format and type values.

missing_query

Add the q parameter to search & community calls.

missing_ids

Provide comma-separated numeric IDs in ids.

missing_params

Required query parameters are missing. Follower checks need both source & target.

too_many_ids

Too many IDs. Split them into groups of 100 or fewer.

invalid_media_url

Send each media entry as an HTTP or HTTPS URL.

unsupported_media_combination

Send 1 MP4 alone, or only images.

unsupported_field

The body has a field this endpoint rejects. Posts take public media URLs in media, not uploaded media IDs.

missing_idempotency_key

The X write has no Idempotency-Key header. Send 1 unique key per intended write, and reuse it only to retry that write.

invalid_idempotency_key

Idempotency-Key doesn’t match the endpoint’s format. Send a random UUID v4, which every endpoint accepts.

invalid_coverage_cursor

Cursor is malformed. Restart without it and deduplicate stored IDs.

invalid_community_topic

Unknown Community topic. Use a name or ID from Community topics.

invalid_cursor

X can’t read the cursor, or it expired. Start again without cursor, then use next_cursor. It costs nothing.

Authentication errors (401)

Missing or invalid credentials. Check your API key or session.

unauthenticated

API key or bearer token is missing or invalid. Send x-api-key or regenerate a revoked key.

x_auth_failure

The X account’s session ended. Re-authenticate it from the dashboard.

Anonymous paid-read authentication (401)

Non-MPP paid reads return 401 with WWW-Authenticate: Bearer and a guest wallet action. This is not a Payment challenge. Authenticate or get confirmation before calling the action.

Billing & credit errors (402)

A 402 creates no checkout. Account and OAuth responses advertise account billing actions. Guest responses advertise only POST /api/v1/guest-wallets/topups. Direct MPP responses include a Payment challenge and guest option. Get confirmation before calling any action. A write’s 402 adds top_up_url & dashboard.

no_subscription

No plan. Check credits, then top up or subscribe.

subscription_inactive

Plan inactive. Remaining credits work. Top up or reactivate on the billing page.

payment_failed

Payment failed. Update the payment method in the dashboard.

no_credits

No credits left. Check Get Account, then use Top Up Credits after confirmation.

insufficient_credits

Balance is below the operation’s cost. Account callers check Get Account, guest callers Guest Wallet Status. Use only the payment action advertised for that credential.

Permission errors (403)

Plan, limits, or account visibility prevent this action.

api_key_limit_reached

The account has 100 active API keys. Revoke one before creating another.

dm_not_permitted

DM history requires a participating connected account. Choose one or reconnect it from the dashboard.

account_needs_reauth

The X account needs re-authentication. Reconnect it from the dashboard, then retry.

account_restricted

Connected X account is locked, suspended, recovering, or temporarily blocked. Resolve account health on x.com or wait before retrying.

Not found errors (404)

The requested resource does not exist, is unavailable to this API key, or is not the expected X object type.

not_found

Lookup failed. Verify the ID belongs to your account and has not been deleted.

account_not_found

No such connected X account. Call List X Accounts and use one it lists.

user_not_found

X shows no profile for the username or user ID. reason says why: not_found or suspended. Confirm the handle, or choose another account when X suspended it.

tweet_not_found

The tweet ID doesn’t resolve. Check it. The author may have deleted the tweet.

no_media

The tweet has no downloadable media. Use a tweet with media.

article_not_found

Valid Tweet ID, but no X Article. Request an Article URL or use tweet or thread endpoints.

draft_not_found

Draft missing. Verify its ID or create one.

style_not_found

Style ID missing. Analyze tweets with Analyze Style.

no_cached_style

No cached style for this username. Analyze tweets with Analyze Style.

Conflict and cursor errors (409/410)

Reuse duplicate monitors. Recover cursors by status and error code.

monitor_already_exists

Duplicate account or keyword monitor. List existing monitors, reuse the monitor ID, or update event types with Update Monitor or Update Keyword Monitor.

coverage_cursor_unavailable

Follow the exact Retry-After seconds. Retry the same cursor once. Repeated busy responses never authorize a fresh extraction.

coverage_cursor_gone

No Retry-After. Restart cursorless and deduplicate IDs. Keep received results. Restarting creates a separate extraction.

Media errors (413/415)

Xquik stops before any X call and charges nothing.

unsupported_media_type

Xquik can’t read the file or its Content-Type. Send a valid, supported file.

media_too_large

The file is too big, even after Xquik shrinks images. Send a smaller file.

Validation errors (422)

Write validation failed. Change the account, target, content, DM permission, or media input before retrying.

x_account_feature_required

Missing account capability. Change the account or request. Creating a community returns it, uncharged, when X blocks the account.

x_account_suspended

X account suspended or restricted. Resolve its status on x.com before further writes.

x_account_protected

Target account is protected. Timeline reads return 403, including continuations. Use a public account. Profiles remain readable. Xquik collects and charges no results. Writes return 422.

x_duplicate_action

Operation is complete. Check the target before retrying. Never repeat an unchanged request.

x_dm_not_allowed

Recipient does not accept DMs from this account. Use a permitted connected account or ask the recipient to allow messages.

x_dm_not_deleted

X still shows the DM. Xquik charges nothing. Retry with a new Idempotency-Key.

x_target_not_found

Target is missing or invisible to the connected X account. Verify the ID and that account’s access before sending another request. Writes also return it for a username X doesn’t know.

x_reply_not_allowed

This account cannot reply to the post. Choose a post it can reply to.

x_reply_target_unavailable

The post you’re replying to is unavailable on X, so Xquik sent nothing. Check the post on x.com or reply to another post.

x_content_too_long

Content exceeds the character limit. Shorten it or use an account that allows longer posts.

x_rejected

X refused the write and said why. Xquik charges nothing. Change the request. Retry only when the durable action marks it safe.

x_automation_refused

X said the write might be automated & refused it. Xquik charges nothing. Send the next request now with a new Idempotency-Key. Waiting does not help. If X keeps refusing, check the account on x.com. Vary your text or pace.

x_media_rejected

X couldn’t read the uploaded file. Upload a valid JPG, PNG, GIF, WebP, or MP4. Do not retry the same file.

x_image_invalid

X refused the image’s size. Send one from 200x100 to 8192x8192 pixels.

media_download_failed

Xquik could not download the public media URL. Fix the HTTPS URL or pass the file via multipart/form-data. Do not retry the same URL.

Active write lifecycle (202)

The durable write remains active. Its status is accepted, dispatching, or pending_confirmation. Follow write lifecycle recovery.

x_post_not_sent

X never published the post. Xquik charges nothing. Post again with a new Idempotency-Key.

Rate limit errors (429)

Request rate exceeded. See Rate Limits for tier details.

rate_limit_exceeded

You reached an Xquik tier or action limit. Wait the Retry-After seconds from the response. JSON also includes retryAfter when available.

login_cooldown

A recent login attempt triggered cooldown. Wait retryAfterMs or the Retry-After header before reconnecting or reauthenticating.

x_rate_limited

X throttled the write. Follow Retry-After, then retry with backoff.

x_daily_limit

Connected X account reached its daily posting limit. Wait 24 hours before retrying that account, or use another connected account.

Server & service errors (500/502/503)

Transient failures. Retry with exponential backoff, up to 3 attempts.

internal_error

Server error. Retry with backoff and contact support if it continues.

x_api_rate_limited

Read service rate limited. Retry in a few minutes.

x_api_unavailable

Read service temporarily unavailable or busy. Respect Retry-After when present, otherwise retry with backoff.

pagination_stalled

Pagination stopped after repeated empty pages. Retry the same cursor once after 30 seconds. A second stall ends the list. Keep returned rows. Deduplicate by ID.

x_api_unauthorized

Read service authentication failed. Retry later and contact support if it continues.

x_write_failed

Xquik could not explain why the write failed. Follow safeToRetry & nextAction. Contact support if it stays unsafe to retry.

x_write_ambiguous

X may have applied the write. X gave 408, 500, 502, 503 or 504 after the send, or no confirmation. Poll the action & check the result before sending again.

x_transient_error

A temporary failure, such as X’s 408, 500, 502, 503 or 504 before the send. Retry only when safeToRetry is true.

Write lifecycle recovery

Writes can return durable actions. Check their lifecycle fields first.

Store the action

Store id, status, request.hash, account, target, billing, and statusUrl.

Poll the write action

Poll statusUrl while terminal is false. Respect Retry-After and pollAfterMs.

Store the outcome

Store result and settled billing after terminal becomes true.

Follow retry safety

Retry only when safeToRetry is true, using a new Idempotency-Key. Verify the result when nextAction.type is verify_result.

Retry with exponential backoff

For reads, retry pagination_stalled once. Otherwise retry 429 and 5xx. Use Retry-After, then exponential backoff with jitter. For writes, follow the durable action’s safeToRetry and nextAction fields instead. Formula. delay = baseDelay * 2^attempt + random(0, jitter)

function retryDelayMs(response: Response, attempt: number): number {
  const retryAfter = response.headers.get("Retry-After");

  if (retryAfter) {
    return Number.parseInt(retryAfter, 10) * 1000;
  }

  return 1000 * 2 ** attempt + Math.floor(Math.random() * 1000);
}

async function shouldRetry(response: Response, attempt: number): Promise<boolean> {
  const body = await response
    .clone()
    .json()
    .catch(() => null);
  if (body?.error === "pagination_stalled") return attempt === 0;
  return response.status === 429 || response.status >= 500;
}

Rate limit handling

HTTP status

429 Too Many Requests signals a rate limit or account cooldown.

Retry-After header

Retry-After gives the seconds to wait before resending.

Without Retry-After, read retryAfter or retryAfterMs from the JSON body. After another 429, back off and stop after 3 attempts.

Best practices

Log status & error codes without credentials or private payloads. Set request timeouts & poll long-running jobs. Deleting missing resources returns 404. Repeating deletion is safe.

Rate limits

Rate limit tiers and client-side limits.

API overview

Base URL, authentication, and conventions.

​Quick reference