> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xquik.com/llms.txt
> Use this file to discover all available pages before exploring further.
# X API error handling for tweet & follower workflows
> Recover Xquik requests, cursors, writes, monitors, webhooks, and dependencies. Follow retry safety, restore account access, and handle reply restrictions.
For the complete documentation index, see llms.txt.
Choose recovery by `error` code.
## Quick reference
Start with HTTP status. Retry only when stated.
Retry: no. Fix the body, query, or path. Examples include
`invalid_json`, `invalid_id`, `invalid_tweet_url`, `invalid_tweet_id`.
Retry: no. Check `x-api-key`, regenerate revoked keys, or re-authenticate
the connected X account. Covers `unauthenticated` and `x_auth_failure`.
Retry: no. Read `payment_options`, then get explicit user confirmation.
Covers `no_subscription`, `subscription_inactive`, `payment_failed`,
`no_credits`, and `insufficient_credits`.
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.
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.
Busy cursor: follow `Retry-After` and retry once. Gone cursor: restart
cursorless and deduplicate IDs.
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](#common-error-codes).
Retry: no. Store the action and poll `statusUrl` while `terminal` is
`false`. Follow `Retry-After`, `pollAfterMs`, and `nextAction`.
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.
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`](https://docs.xquik.com/openapi.yaml) schema lists every public code.
**Default response.**
```json theme={null}
{ "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`.
Invalid body, query, or path.
Invalid body. Check the endpoint's required fields, types & enum values.
Invalid JSON body. Send a parseable JSON object.
Invalid path ID. Use the create or list endpoint's numeric string.
Tweet URL is malformed. Use `https://x.com/user/status/ID`.
Send a post ID or post URL, such as `x.com/nasa/status/20`.
Username is empty or invalid. Send a username without the `@` prefix.
Send a user ID, `@username` or profile URL, such as `x.com/nasa`.
Send a DM ID from [DM history](/api-reference/x/dm-history).
Add your connected X account, such as `?account=@nasa`.
Unknown extraction tool type. Use one of the 23 types from
[Create Extraction](/api-reference/extractions/create).
Export format is unsupported. Use `csv`, `json`, `md`, `md-document`,
`pdf`, `txt`, or `xlsx`.
Invalid export query. Check the `format` and `type` values.
Add the `q` parameter to search & community calls.
Provide comma-separated numeric IDs in `ids`.
Required query parameters are missing. Follower checks need both source
& target.
Too many IDs. Split them into groups of 100 or fewer.
Send each `media` entry as an HTTP or HTTPS URL.
Send 1 MP4 alone, or only images.
The body has a field this endpoint rejects. Posts take public media URLs
in `media`, not uploaded media IDs.
The X write has no `Idempotency-Key` header. Send 1 unique key per
intended write, and reuse it only to retry that write.
`Idempotency-Key` doesn't match the endpoint's format. Send a random UUID
v4, which every endpoint accepts.
Cursor is malformed. Restart without it and deduplicate stored IDs.
Unknown Community topic. Use a name or ID from
[Community topics](/api-reference/x/community-topics).
X can't read the cursor, or it expired. Start again without `cursor`,
then use `next_cursor`. It costs nothing.
Missing or invalid credentials. Check your API key or session.
API key or bearer token is missing or invalid. Send `x-api-key` or
regenerate a revoked key.
The X account's session ended. Re-authenticate it from the
[dashboard](https://xquik.com/dashboard).
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.
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 plan. Check credits, then [top up](/api-reference/credits/topup) or [subscribe](/api-reference/account/subscription-checkout).
Plan inactive. Remaining credits work. Top up or reactivate on the [billing page](https://dashboard.xquik.com/en/account?tab=subscription).
Payment failed. Update the payment method in the
[dashboard](https://xquik.com/subscription).
No credits left. Check [Get Account](/api-reference/account/get), then
use [Top Up Credits](/api-reference/credits/topup) after confirmation.
Balance is below the operation's cost. Account callers check
[Get Account](/api-reference/account/get), guest callers
[Guest Wallet Status](/api-reference/guest-wallets/status). Use only the
payment action advertised for that credential.
Plan, limits, or account visibility prevent this action.
The account has 100 active API keys. Revoke one before creating another.
DM history requires a participating connected account. Choose one or reconnect it from the
[dashboard](https://xquik.com/dashboard).
The X account needs re-authentication. Reconnect it from the
[dashboard](https://xquik.com/dashboard), then retry.
Connected X account is locked, suspended, recovering, or temporarily
blocked. Resolve account health on x.com or wait before retrying.
The requested resource does not exist, is unavailable to this API key, or
is not the expected X object type.
Lookup failed. Verify the ID belongs to your account
and has not been deleted.
No such connected X account. Call
[List X Accounts](/api-reference/x-accounts/list) and use one it lists.
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.
The tweet ID doesn't resolve. Check it. The author may have deleted the
tweet.
The tweet has no downloadable media. Use a tweet with media.
Valid Tweet ID, but no X Article. Request an Article URL or use tweet or thread endpoints.
Draft missing. Verify its ID or create one.
Style ID missing. Analyze tweets with
[Analyze Style](/api-reference/styles/analyze).
No cached style for this username. Analyze tweets with [Analyze Style](/api-reference/styles/analyze).
Reuse duplicate monitors. Recover cursors by status and error code.
Duplicate account or keyword monitor. List existing monitors, reuse the
monitor ID, or update event types with
[Update Monitor](/api-reference/monitors/update) or
[Update Keyword Monitor](/api-reference/monitors/update-keyword).
Follow the exact `Retry-After` seconds. Retry the same cursor once.
Repeated busy responses never authorize a fresh extraction.
No `Retry-After`. Restart cursorless and deduplicate IDs.
Keep received results. Restarting creates a separate extraction.
Xquik stops before any X call and charges nothing.
Xquik can't read the file or its `Content-Type`. Send a valid, supported file.
The file is too big, even after Xquik shrinks images. Send a smaller file.
Write validation failed. Change the account, target, content, DM
permission, or media input before retrying.
Missing account capability. Change the account or request.
Creating a community returns it, uncharged, when X blocks the account.
X account suspended or restricted. Resolve its status on x.com before further writes.
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.
Operation is complete. Check the target before retrying. Never repeat an unchanged request.
Recipient does not accept DMs from this account. Use a permitted
connected account or ask the recipient to allow messages.
X still shows the DM. Xquik charges nothing. Retry with a new `Idempotency-Key`.
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.
This account cannot reply to the post. Choose a post it can reply to.
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.
Content exceeds the character limit. Shorten it or use an account that
allows longer posts.
X refused the write and said why. Xquik charges nothing. Change the request.
Retry only when the durable action marks it safe.
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 couldn't read the uploaded file. Upload a valid JPG, PNG, GIF, WebP,
or MP4. Do not retry the same file.
X refused the image's size. Send one from 200x100 to 8192x8192 pixels.
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.
The durable write remains active. Its status is `accepted`, `dispatching`,
or `pending_confirmation`. Follow
[write lifecycle recovery](#write-lifecycle-recovery).
X never published the post. Xquik charges nothing. Post again with a new `Idempotency-Key`.
Request rate exceeded. See [Rate Limits](/guides/rate-limits) for tier details.
You reached an Xquik tier or action limit. Wait the `Retry-After` seconds
from the response. JSON also includes `retryAfter` when available.
A recent login attempt triggered cooldown. Wait `retryAfterMs` or the
`Retry-After` header before reconnecting or reauthenticating.
X throttled the write. Follow `Retry-After`, then retry with backoff.
Connected X account reached its daily posting limit. Wait 24 hours
before retrying that account, or use another connected account.
Transient failures. Retry with exponential backoff, up to 3 attempts.
Server error. Retry with backoff and
[contact support](mailto:support@xquik.com) if it continues.
Read service rate limited. Retry in a few minutes.
Read service temporarily unavailable or busy. Respect `Retry-After`
when present, otherwise retry with backoff.
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.
Read service authentication failed. Retry later and
[contact support](mailto:support@xquik.com) if it continues.
Xquik could not explain why the write failed. Follow `safeToRetry` &
`nextAction`. Contact support if it stays unsafe to retry.
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.
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 `id`, `status`, `request.hash`, `account`, `target`, `billing`, and
`statusUrl`.
Poll `statusUrl` while `terminal` is `false`. Respect `Retry-After` and
`pollAfterMs`.
Store `result` and settled `billing` after `terminal` becomes `true`.
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)`
```ts theme={null}
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 {
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
`429 Too Many Requests` signals a rate limit or account cooldown.
`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 limit tiers and client-side limits.
Base URL, authentication, and conventions.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.