Skip to main content
This page lists common issues, error codes, and fixes. If it does not cover your problem, contact support@xquik.com.

Error codes

401 Unauthenticated

The API key or OAuth token is missing, invalid, expired, or revoked. Check the following items.
  • 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, pausing, and revoking keys require a same-origin dashboard session. API keys and OAuth bearer tokens cannot manage keys.

403 paused API key

api_key_paused means this key is paused. Resume it on the API keys page, and the next request goes through. Pausing never deletes the key or its settings.

403 insufficient scope

insufficient_scope means the key lacks a scope this route needs. requiredScope names it. Add it on the API keys page, then retry.

403 IP not allowed

ip_not_allowed means the key has an IP allowlist without the calling IP. The message names that IP. Add it on the API keys page, or call from a listed IP. An empty list allows any IP.

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. Try these fixes.
  • For account keys, check GET /api/v1/account and use only the advertised account payment action
  • For guest keys, check guest wallet status. Then use only the advertised guest top-up action
  • For the direct MPP operations, complete the MPP challenge. You can also ask the user to confirm a guest wallet amount
  • For the other guest-eligible reads, authenticate. You can also ask the user to confirm a guest wallet amount
  • Use Estimate Extraction 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 30 credits per hour. They require available credits while enabled.
Try these fixes.
  • 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 with GET /api/v1/account, which shows monitorsUsed and monitorBilling

403 API key budget reached

The call doesn’t fit what’s left of the key’s monthly credit budget. It never ran and cost nothing. A read with a limit needs that many results’ price left. A write needs its price plus 20 credits left. Other keys on the account keep working.
Try these fixes.
  • Raise or remove monthlyBudgetCredits with Update API key. The next call works.
  • Wait for the next UTC month, when the key’s spend starts again at 0.
  • Compare monthlySpentCredits across keys with List API keys to find unexpected usage.

429 Too many requests

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

Read

GET, HEAD, and OPTIONS share 500 requests per 1 second.

Change

Other methods on Xquik resources share 6,000 requests per 60 seconds.

X action

Actions through a connected X (Twitter) account share 120 requests per 60 seconds.
Try these fixes.
  • 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 guide for backoff code examples.

502/503 Read service busy or unavailable

The read service is temporarily unavailable or busy. This is usually transient.Try these fixes.
  • 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)
  • After 5 minutes of errors, the read service may have an outage
The same applies to draws. So do 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 guide for a step-by-step local setup with ngrok.

Monitor not tracking events?

If your monitor is active but no events appear, check these items.
  • 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 next time. 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.
  • creditInfo.balance shows the remaining credits available for metered calls
  • At a balance of 0, Xquik rejects metered calls. A credit top-up or an auto top-up ends that
  • Auto top-up stops after 3 declined charges in a row. Update your card in the dashboard to restart it.
  • With exchange rates over 3 ECB working days old, non-USD auto top-ups skip. Nothing is charged.
The dashboard billing page also charts usage. See Billing & Usage 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. 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.

Search docs

Connect https://docs.xquik.com/mcp. It is read-only and requires no auth.

Run API actions

Connect https://xquik.com/mcp. Full credentials expose every JSON or text route. Guest paid_reads keys expose the eligible paid-read routes.
Follow these setup steps.
  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.These are the current client paths.
  • OAuth 2.1. Claude.ai, Claude Desktop, Claude Code, ChatGPT, Cursor, VS Code, Windsurf, and OpenCode. Gemini CLI, GitHub Copilot CLI, Cline and Qwen Code also use it. So do 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 for docs search. See MCP Server overview for account actions. The MCP Tools reference has the tool details.

MCP OAuth does not open or shows an unknown application

Use this checklist.
  1. Enter https://xquik.com/mcp as the exact server URL.
  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 is at https://xquik.com/.well-known/oauth-protected-resource/mcp
  • Authorization server metadata is at https://xquik.com/.well-known/oauth-authorization-server
  • The agent-readable auth guide is at https://xquik.com/auth.md
Xquik supports CIMD and DCR. Let the client use its documented registration flow. Claude selects CIMD when 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, check its public HTTPS metadata URL. It 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.Exports work like this.
  • Exports include every row. A PDF above 10,000 rows comes as a ZIP of PDF parts
  • Available formats are CSV, JSON, Markdown, Markdown Document, PDF, TXT, and XLSX
See Export Extraction for column details and code examples.

Still stuck?

  • Authentication covers API key format, header requirements, and dual auth details.
  • Error Handling covers error codes, retry strategies, and graceful degradation.
  • Billing & Usage covers pricing, credits, and per-operation costs.