> ## 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.

# Troubleshooting

> Common issues and solutions for the Xquik API including authentication, rate limits, and webhook delivery errors

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

Common issues, error codes, and solutions. If your problem isn't covered here, contact [support@xquik.com](mailto:support@xquik.com).

## Error codes

### 401 Unauthenticated

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

* **Header name:** Must be `x-api-key` (lowercase). `Authorization` or `X-Api-Key` won't work.
* **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.
* **API key management auth:** Use a dashboard session cookie to create the first key. Existing API keys or OAuth bearer tokens can list, create, and revoke keys for the same account.

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

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

### 402 No Subscription / Insufficient Credits

No active subscription or insufficient credits. Possible error codes: `no_subscription`, `subscription_inactive`, `no_credits`, `insufficient_credits`. This affects metered endpoints (draws, extractions, tweet lookups, user lookups, follower checks).

Solutions:

* Check your remaining balance via `GET /api/v1/account` (`creditInfo.balance` field)
* [Top up credits](/api-reference/credits/topup) from the dashboard
* Use [Estimate Extraction](/api-reference/extractions/estimate) before running extractions to avoid surprises

Management endpoints (stored monitors, events, webhooks, API keys, account) are not affected and continue to work normally.

### Monitor Credits

Monitor slots are unlimited. Active instant monitors cost 21 credits per hour and 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 with `DELETE /api/v1/monitors/{id}` or `DELETE /api/v1/monitors/keywords/{id}`
* 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 a limit of 60 requests per 1 second.
  </Card>

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

  <Card title="Delete" icon="circle-x">
    `DELETE` requests are limited to 15 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. Webhooks push events to you in real time, eliminating the need for repeated API 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-10 seconds
* Use exponential backoff (see [Error Handling](/guides/error-handling))
* If the error persists for more than 5 minutes, the read service may be experiencing an outage

The same applies to draws and X data lookup endpoints (`/api/v1/x/*`).

## Common questions

### Webhooks not arriving?

Webhooks can fail silently. Walk through this checklist:

1. **Webhook is active:** Verify `isActive: true` and `deliveryStatus: "active"` via `GET /api/v1/webhooks`. Paused webhooks do not receive deliveries.
2. **HTTPS required:** HTTP endpoints are rejected. Your URL must start with `https://`.
3. **Response time:** We recommend responding with `2xx` within 10 seconds. Slow responses may be treated as failures.
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:** If `deliveryStatus` is `needs_attention`, fix the receiver and call `POST /api/v1/webhooks/{id}/resume`. The receiver must pass a signed test before delivery resumes.
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/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 actually post content matching your event types. No posts = 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 `after` on the next request. Add `eventType` when you need to separate follows, tweets, replies, or keyword matches.

### Write action still pending?

If a tweet or reply returns `202 x_write_unconfirmed`, the send was dispatched
but final confirmation is pending.

* Store `writeActionId`, `status`, `charged`, and `chargedCredits`
* Do not retry-send the same post while status is `pending_confirmation`
* Poll `GET /api/v1/x/write-actions/{id}` before scheduling follow-up work
* Store `tweetId` only after the status response confirms success

### 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`, metered calls are rejected until credits are topped up or auto top-up triggers

The dashboard also displays usage graphically on the billing page.

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

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

Partially. Non-metered endpoints work without an active subscription:

* **Work without subscription:** Reading, updating, and deleting stored monitors, events, webhooks, API keys, and account management
* **Require subscription:** Creating active monitors, draws, extractions, and X API lookups (tweets, users, follower checks) return `402` with `no_subscription`

Subscribe from the [dashboard](https://xquik.com) billing page to unlock metered endpoints. Access activates immediately after payment.

### 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`. It requires `x-api-key` or OAuth 2.1 and exposes `explore` plus `xquik`.
  </Card>
</CardGroup>

Setup:

1. For docs search, add `https://docs.xquik.com/mcp`.
2. For account actions, get your API key from the dashboard.
3. Configure `https://xquik.com/mcp` with an `x-api-key` header or OAuth login.

Supported clients:

* Claude Desktop, Claude Code, ChatGPT (via Agents SDK), Codex CLI, Cursor, VS Code, Windsurf, OpenCode

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.

### How do I export extraction results?

Call `GET /api/v1/extractions/{id}/export?format=csv` (or `xlsx` or `md`). 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.