> ## 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 troubleshooting for tweets, exports & webhooks

> Fix API key, credit, rate-limit, cursor, tweet lookup, follower export, write-action, extraction, monitor, and webhook delivery errors. Follow exact steps.

<blockquote className="agent-llms-directive">
  For the complete documentation index, see <a href="/llms.txt">llms.txt</a>.
</blockquote>

This page lists common issues, error codes, and fixes. If it does not cover your problem, contact [support@xquik.com](mailto:support@xquik.com).

## Error codes

### 401 Unauthenticated

The API key or OAuth token is missing, invalid, expired, or revoked. Check the
following:

* **API key header.** Send `x-api-key: xq_...` or `Authorization: Bearer xq_...`.
* **OAuth header.** Send `Authorization: Bearer <access_token>`. OAuth clients normally manage this automatically.
* **Key format.** Must start with `xq_`. If it doesn't, you're using the wrong value.
* **Key revoked.** Revoked keys return 401 immediately. Generate a new key from the dashboard.
* **OAuth token expired.** Let the MCP client refresh the token. Reconnect Xquik if refresh fails.
* **API key management auth.** Listing, creating, and revoking keys require a same-origin dashboard session. API keys and OAuth bearer tokens cannot manage keys.

```bash theme={null}
# Correct
curl https://xquik.com/api/v1/account \
  -H "x-api-key: xq_your_api_key_here"

# Wrong - missing header
curl https://xquik.com/api/v1/account
```

### 401 authentication or 402 payment required

Anonymous non-MPP paid reads return `401` with a Bearer challenge and guest wallet action. Direct MPP reads return `402` with a Payment challenge and the same action. Account or guest credit failures also return `402`. The failed request creates no checkout.

Solutions:

* For account keys, check `GET /api/v1/account` and use only the advertised account payment action
* For guest keys, check [guest wallet status](/api-reference/guest-wallets/status) and use only the advertised guest top-up action
* For the direct MPP operations, complete the MPP challenge or ask the user to confirm a guest wallet amount
* For the other guest-eligible reads, authenticate or ask the user to confirm a guest wallet amount
* Use [Estimate Extraction](/api-reference/extractions/twitter-scraping-cost-estimator) to see the credit cost before running extractions

Ask the user to choose an option and amount before creating checkout. Never trigger checkout, top-up, or subscription automatically after `401` or `402`.

### Monitor credits

Monitor slots are unlimited. Active monitors cost 21 credits per hour. They
require available credits while enabled.

```json theme={null}
{ "error": "insufficient_credits", "message": "Insufficient credits" }
```

Solutions:

* Pause an unused account monitor with `PATCH /api/v1/monitors/{id}` and `{ "isActive": false }`
* Pause an unused keyword monitor with `PATCH /api/v1/monitors/keywords/{id}` and `{ "isActive": false }`
* Delete an unused monitor. Poll the returned `statusUrl` until it returns `404`.
* Check current monitor billing: `GET /api/v1/account` shows `monitorsUsed` and `monitorBilling`

### 429 Too many requests

You've exceeded the API rate limit. The API uses fixed windows per tier:

<CardGroup cols={3}>
  <Card title="Read" icon="database">
    `GET`, `HEAD`, and `OPTIONS` share 500 requests per 1 second.
  </Card>

  <Card title="Write" icon="pen-line">
    `POST`, `PUT`, and `PATCH` share 120 requests per 60 seconds.
  </Card>

  <Card title="Delete" icon="circle-x">
    `DELETE` allows 60 requests per 60 seconds.
  </Card>
</CardGroup>

Solutions:

* Respect `Retry-After`. Otherwise start at 1 second, add jitter, and stop after 3 retries.
* Requests sent before the fixed window resets keep returning `429` until `Retry-After` elapses.
* Check the `Retry-After` header for the server-recommended wait time.
* Use webhooks instead of polling. They push detected events without repeated event-list calls.
* Batch your logic. Fetch events once per minute instead of once per second.

See the [Rate Limits](/guides/rate-limits) guide for backoff code examples.

### 502/503 Read service busy or unavailable

The read service is temporarily unavailable or busy. This is usually transient.

Solutions:

* Respect `Retry-After` when present, then retry the request
* If no `Retry-After` header is present, retry after 5 to 10 seconds
* Use exponential backoff (see [Error Handling](/guides/error-handling))
* If the error continues for more than 5 minutes, the read service may have an outage

The same applies to draws and tweet, profile, follower, reply, timeline, community, and list endpoints under `/api/v1/x/*`.

## Common questions

### Webhooks not arriving?

Webhook delivery can fail without a visible error. Check each item:

1. **Webhook is active.** Verify `isActive: true` and `deliveryStatus: "active"` via `GET /api/v1/webhooks`. Paused webhooks do not receive deliveries.
2. **HTTPS required.** Xquik rejects HTTP endpoints. Your URL must start with `https://`.
3. **Response time.** Respond with `2xx` within 10 seconds, even for events you skip. Slower responses and rejections count as failures. A failure can delay new deliveries by up to 15 minutes.
4. **Check deliveries.** Call `GET /api/v1/webhooks/{id}/deliveries` to see delivery status, attempt count, and error messages.
5. **Correlate source events.** Call `GET /api/v1/events/{id}` with the stored `streamEventId`.
6. **Local testing.** If using ngrok or a tunnel, verify it's running and the URL is current. Ngrok URLs change on restart (free plan).
7. **Needs attention.** `needs_attention` means 200 failed checks in a row. Xquik keeps retrying. Fix the receiver, then call `POST /api/v1/webhooks/{id}/resume`. It starts sending waiting deliveries at once.
8. **Event type mismatch.** Your webhook must subscribe to the event types your monitors produce. A webhook listening for `tweet.new` won't receive `tweet.reply` events.

> **Tip.** See the [Webhook Testing](/guides/twitter-webhook-testing) guide for a step-by-step local setup with ngrok.

### Monitor not tracking events?

If your monitor is active but no events appear:

* **Check `isActive`.** Confirm via `GET /api/v1/monitors/{id}` that `isActive` is `true`. Paused monitors don't track.
* **Event propagation delay.** Events take seconds to minutes to appear depending on X API latency. This is normal.
* **Event types.** Verify your monitor's `eventTypes` array includes the type you expect. A monitor tracking only `["tweet.new"]` won't capture replies or retweets.
* **Account activity.** The monitored X account must post content matching your event types. No posts means no events.
* **Pagination.** If listing events, check `hasMore` in the response. Older events may be on subsequent pages.

### How do I replay stored monitor events?

Call `GET /api/v1/events?monitorId={id}&limit=50` for account monitors, or
`GET /api/v1/events?keywordMonitorId={id}&limit=50` for keyword monitors, then
process each event once. If `hasMore` is `true`, store `nextCursor` and pass it as `cursor` on the next request. Add `eventType` when you need to separate tweets, replies, quotes, or profile changes.

### Write action still pending?

Inspect the durable action returned by the write.

* Store `id`, `request.hash`, `account`, `target`, `billing`, and `statusUrl`
* Poll `statusUrl` while `terminal` is `false`
* Respect `Retry-After`, `pollAfterMs`, and `nextAction`
* Retry only when `safeToRetry` is `true`, using a new `Idempotency-Key`
* Verify the result before retrying when `nextAction.type` is `verify_result`

### How do I check my usage?

Call `GET /api/v1/account`. The `creditInfo` object shows your balance:

```json theme={null}
{
  "creditInfo": {
    "balance": "42500",
    "lifetimePurchased": "140000",
    "lifetimeUsed": "97500",
    "autoTopupEnabled": false
  }
}
```

* `creditInfo.balance`: Remaining credits available for metered calls
* When `balance` reaches `0`, Xquik rejects metered calls until you top up credits or auto top-up triggers
* Auto top-up stops after 3 declined charges in a row. Update your card in the dashboard to restart it.

The dashboard billing page also charts usage.

See [Billing & Usage](/guides/billing) for credit costs and billing.

### Can I use the API without a subscription?

Yes. Full account metered operations work while enough available credits remain. Choose the access boundary:

* **Guest wallet.** Prepay the eligible paid-read routes through a confirmed USD 10 to 250 hosted checkout.
* **MPP.** Pay per request on fixed-price GET operations without an account or API key.
* **Full account.** Use available account credits for writes, monitors, extractions, draws, and connected-account reads. Webhooks and account management are free.

Subscribe for monthly credits or top up from the [dashboard billing page](https://dashboard.xquik.com/en/account?tab=subscription). Remaining credits stay usable after a plan ends.

### How do I connect an AI agent?

Xquik has 2 MCP servers. Choose based on what the agent needs to do.

<CardGroup cols={2}>
  <Card title="Search docs" icon="book-open">
    Connect `https://docs.xquik.com/mcp`. It is read-only and requires no auth.
  </Card>

  <Card title="Run API actions" icon="terminal">
    Connect `https://xquik.com/mcp`. Full credentials expose every JSON or text route. Guest `paid_reads` keys expose the eligible paid-read routes.
  </Card>
</CardGroup>

Setup:

1. For docs search, add `https://docs.xquik.com/mcp`.
2. For account actions, use a full API key or OAuth login. Prefer OAuth when the client supports browser authorization.
3. For guest reads, activate a guest key through direct REST, then authenticate MCP with that key.

Guest wallet creation, status, and top-up are never executable through MCP.

Current client paths are:

* **OAuth 2.1.** Claude.ai, Claude Desktop, Claude Code, ChatGPT, Cursor, VS Code, Windsurf, OpenCode, Gemini CLI, GitHub Copilot CLI, Cline, Qwen Code, Pi, Goose, and Codex CLI
* **API-key only.** Roo Code's archived final release has no MCP OAuth provider
* **Older Pi.** Builds without `pi mcp` require an upgrade or a tested adapter

See [Docs MCP server](/mcp/docs-mcp) for docs search, [MCP Server overview](/mcp/overview) for account actions, and the [MCP Tools](/mcp/tools) reference for tool details.

### MCP OAuth does not open or shows an unknown application

Use this checklist:

1. Enter the exact server URL: `https://xquik.com/mcp`.
2. Remove any manually entered client ID or client secret unless your client requires preregistration.
3. Remove and re-add the connector to restart OAuth discovery.
4. Start login from the MCP client. Do not open `/api/auth/google` directly.
5. Allow the browser to return to the client's exact callback URL.

Xquik publishes all required discovery documents:

* Protected resource metadata: `https://xquik.com/.well-known/oauth-protected-resource/mcp`
* Authorization server metadata: `https://xquik.com/.well-known/oauth-authorization-server`
* Agent-readable auth guide: `https://xquik.com/auth.md`

Xquik supports CIMD and DCR. Let the client use its documented registration
flow. Claude selects CIMD when the authorization metadata advertises support
and the public `none` authentication method. Otherwise it can use DCR. ChatGPT
app creators choose CIMD or DCR during setup. If a URL-form `client_id` fails,
its public HTTPS metadata URL must include an explicit path. A trailing `/` is
sufficient. It must return JSON
without a redirect. Repeat the exact URL in `client_id`. List the callback in
`redirect_uris`.

### How do I export extraction results?

Call `GET /api/v1/extractions/{id}/export?format=csv`. Other formats are `json`, `xlsx`, `md`, `md-document`, `pdf`, and `txt`. The response is a file download.

Limits:

* Maximum 100,000 rows per export (10,000 for PDF)
* Available formats: CSV, JSON, Markdown, Markdown Document, PDF, TXT, XLSX

See [Export Extraction](/api-reference/extractions/export) for column details and code examples.

## Still stuck?

* [Authentication](/api-reference/authentication): API key format, header requirements, and dual auth details.
* [Error Handling](/guides/error-handling): Error codes, retry strategies, and graceful degradation.
* [Billing & Usage](/guides/billing): Pricing, credits, and per-operation costs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.