> ## 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.
# Error handling
> Recover from Xquik API error codes and rate limits
For the complete documentation index, see llms.txt.
Every error includes an `error` code. Use it to choose recovery.
Fix your request body. See [validation errors](#error-codes-detailed).
Check your balance or subscription. See [billing errors](#error-codes-detailed) or [billing guide](/guides/billing).
Implement backoff. See [retry strategy](#retry-with-exponential-backoff) or [rate limits](/guides/rate-limits).
## Quick reference
Start with the HTTP family, then apply the recovery rule. Retry only when a
card says the error is retryable.
Retry: no. Fix the body, query, or path. Covers `invalid_input`,
`invalid_json`, `invalid_id`, `invalid_tweet_url`, `invalid_tweet_id`,
`invalid_username`, `invalid_user_id`, `invalid_tool_type`,
`invalid_format`, `invalid_params`, `missing_query`, `missing_ids`,
`missing_params`, `too_many_ids`, and `unsupported_field`.
Retry: no. Check `x-api-key`, regenerate revoked keys, or re-authenticate
the connected X account. Covers `unauthenticated` and `x_auth_failure`.
Retry: no. Subscribe, reactivate billing, update payment, or top up credits.
Covers `no_subscription`, `subscription_inactive`, `no_addon`,
`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`, `monitor_limit_reached`,
`dm_not_permitted`, `account_needs_reauth`, and `account_restricted`.
Retry: no. Verify the resource ID, connected account, username, tweet ID,
media, article, draft, or cached style. Covers `not_found`,
`account_not_found`, `user_not_found`, `tweet_not_found`, `no_media`,
`article_not_found`, `draft_not_found`, `style_not_found`, and
`no_cached_style`.
Retry: no. Use the existing monitor or update it. Covers
`monitor_already_exists`.
Retry: no. Fix the account capability, target, content, DM permissions, or
media URL before sending again. Covers `x_account_feature_required`,
`x_account_suspended`, `x_account_protected`, `x_duplicate_action`,
`x_dm_not_allowed`, `x_target_not_found`, `x_content_too_long`,
`x_rejected`, and `media_download_failed`.
Retry: no. Store `writeActionId`, poll
[Get Write Action Status](/api-reference/x-write/get-write-action-status),
and do not retry-send while status is `pending_confirmation`. Covers
`x_write_unconfirmed`.
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`, `x_api_unauthorized`, `x_write_failed`, and
`x_transient_error`. Stop after 3 attempts. For `x_write_ambiguous`, verify
the result manually before sending anything again.
## Error codes (detailed)
**Response format:**
```json theme={null}
{ "error": "error_code", "message": "Human-readable description" }
```
Some errors include additional context fields (e.g. `limit`, `retryAfter`).
Request body, query, or path validation failed. Fix the request shape before
retrying.
Request body failed validation. Check required fields, types, and enum
values against the endpoint docs.
Request body is not valid JSON. Rebuild the body and send a parseable
JSON object.
Path ID is not valid. Use the numeric string returned by the create or
list endpoint.
Tweet URL is malformed. Use the full format
`https://x.com/user/status/ID`.
Tweet ID is empty or malformed. Extract the final numeric status ID
before calling tweet, media, or article endpoints.
Username or user path value is empty or invalid. Send a username without
the `@` prefix, or send a numeric user ID where supported.
User lookup input is invalid or does not resolve. Check the username or
numeric user ID before retrying.
Extraction tool type is not recognized. Use one of the 23 valid tool
types from [Create Extraction](/api-reference/extractions/create).
Export format is unsupported. Use `csv`, `json`, `md`, `md-document`,
`pdf`, `txt`, or `xlsx`.
Export query parameters are invalid. Check the `format` and `type`
values for that export endpoint.
Required search query is missing. Add the `q` parameter before calling
search or community endpoints.
Required multi-ID query is missing. Provide comma-separated numeric IDs
in the `ids` parameter.
Required query parameters are missing. Check the endpoint docs; follower
checks require both source and target.
Too many IDs were requested at once. Split requests into groups of 100
IDs or fewer.
Request body contains a field this endpoint does not accept. For tweet
posts, send public media URLs in `media`, not uploaded media IDs.
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.
Connected X account session expired or was invalidated. Re-authenticate
the account from the [dashboard](https://xquik.com/dashboard).
Subscription or payment issue. See [Billing & Usage](/guides/billing) for plan details.
No active plan. Start billing from the
[dashboard](https://xquik.com/dashboard) or call
[Subscribe](/api-reference/account/subscribe).
Subscription is inactive. Reactivate billing from the
[dashboard](https://xquik.com/dashboard).
Legacy monitor add-on state. Check billing status; current plans include
unlimited monitor slots.
Payment processing failed. Update the payment method from the
[dashboard](https://xquik.com/subscription).
No credit balance is available. Check balance with
[Get Account](/api-reference/account/get), then top up or subscribe.
Balance is below the required operation cost. Check
[Get Account](/api-reference/account/get), then
[Top Up Credits](/api-reference/credits/topup).
Action not allowed under current plan or limits.
The account already has 100 active API keys. Revoke an active key
before creating another.
Legacy monitor slot limit. Check billing status; current plans include
unlimited monitor slots.
DM history requires a connected account that participates in the
conversation. Use a participating account or reconnect it from the
[dashboard](https://xquik.com/dashboard).
Connected X account session needs re-authentication. Reconnect the
account 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.
Generic resource lookup failed. Verify the ID belongs to your account
and has not been deleted.
Connected X account was not found for this user. Call
[List X Accounts](/api-reference/x-accounts/list) and use a valid
connected account.
X username or numeric user ID does not resolve. Confirm the username
with the user or try a different handle.
Tweet ID does not resolve. Check the numeric tweet ID; the tweet may
have been deleted.
Tweet exists but has no downloadable media attachments. Use a tweet
that contains media.
Tweet ID is valid but is not an X Article. Ask for an X Article URL or
use a normal tweet or thread endpoint.
Draft ID does not exist. Verify the draft ID or create a new draft.
Writing style ID was not found. Analyze tweets first with
[Analyze Style](/api-reference/styles/analyze).
No cached writing style exists for username lookup. Analyze tweets
first with [Analyze Style](/api-reference/styles/analyze).
A monitor with the same target already exists. Treat the response as a
handoff to the existing monitor instead of retrying creation.
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).
Write validation failed. Change the account, target, content, DM
permission, or media input before retrying.
Account capability is missing. Use an account with the required
capability or adjust the request.
Connected X account is suspended or restricted. Resolve account status
on x.com before sending more writes from it.
Target account is protected. Request access first or choose a target
account that the connected account can interact with.
Operation is already complete. Do not retry unchanged; check the target
state before sending anything again.
Recipient does not accept DMs from this account. Use a permitted
connected account or ask the recipient to allow messages.
Tweet or user target does not exist. Verify the ID or username before
sending another request.
Content exceeds the character limit. Shorten the text or use an account
that supports the requested content length.
X rejected the write without a specific reason. Change the request,
wait 2-3 minutes after rapid attempts, then retry changed content.
Public media URL could not be downloaded. Fix the HTTPS URL or pass the
file via multipart/form-data. Do not retry the same URL.
The write action was dispatched, but final confirmation is still pending.
Action may have completed but could not be confirmed. The response
includes `status: "pending_confirmation"`, `writeActionId`,
`charged: false`, and `retryable: false`.
Store `writeActionId`, call [Get Write Action Status](/api-reference/x-write/get-write-action-status), and do not retry-send while status is `pending_confirmation`.
Request rate exceeded. See [Rate Limits](/guides/rate-limits) for tier details.
Xquik tier or action limit was reached. 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. Wait 2-3 minutes, avoid rapid consecutive
requests to the same account, 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 (max 3 attempts).
Server error. Retry with backoff and
[contact support](mailto:support@xquik.com) if it persists.
Read service rate limited. Retry in a few minutes.
Read service temporarily unavailable or busy. Respect `Retry-After`
when present, otherwise retry with backoff.
Read service authentication failed. Retry later and
[contact support](mailto:support@xquik.com) if it persists.
Write action failed unexpectedly. Retry the request and
[contact support](mailto:support@xquik.com) if it persists.
Write action completion could not be confirmed. Verify the result
manually before sending anything again.
Write service timeout or temporary failure. Retry with backoff.
## Write confirmation recovery
Because `202` is a successful HTTP status, check `response.status` before
generic `response.ok` handling. This keeps pending tweet and reply writes out of
your normal success path.
If `response.status === 202` and `error === "x_write_unconfirmed"`, store `writeActionId`, `status`, `charged`, `chargedCredits`, and `retryable`.
Poll `GET /api/v1/x/write-actions/{id}` until `status` is `success` or `failed`.
Only persist `tweetId` or `messageId` after the status endpoint confirms success.
Do not retry-send while the write action status is `pending_confirmation`.
## Retry with exponential backoff
Retry only on `429` and `5xx` responses. Use the `Retry-After` header first,
then exponential backoff with jitter. Stop after 3 attempts.
**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);
}
function shouldRetry(response: Response): boolean {
return response.status === 429 || response.status >= 500;
}
```
## Rate limit handling
When a request is rate limited, Xquik returns `429 Too Many Requests` with a
`Retry-After` header. Some JSON bodies also include `retryAfter` in seconds or
`retryAfterMs` in milliseconds for login cooldowns.
`429 Too Many Requests` means the request is rate limited or waiting on an
account cooldown.
The `Retry-After` header gives seconds to wait before sending the same
request again.
Branch on `response.status === 429` before normal success handling.
Parse `Retry-After` as seconds. If it is missing, read `retryAfter` or `retryAfterMs` from the JSON body.
Do not send another request for the same operation until the wait expires.
If the same request returns another 429, apply exponential backoff and stop after 3 attempts.
## Best practices
**4xx errors** (except 429) indicate a problem with your request. Fix the request before retrying. **5xx errors** and **429** are transient. Retry with backoff.
Always log the full error response including status code and error body. This makes it easy to diagnose issues in production.
`monitor_already_exists` is not a failure. The monitor you need already exists. List monitors to find it instead of treating this as an error.
Set a 30-second timeout on all API requests. If a request hangs, retry it rather than waiting indefinitely.
Creating a monitor for the same username returns `409`. Deleting a non-existent resource returns `404`. Both are safe to retry.
Detailed rate limit tiers and client-side rate limiting.
Base URL, authentication, and API conventions.