Common issues, error codes, and solutions. If your problem isn’t covered here, contact support@xquik.com.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 codes
401 Unauthenticated
The API key is missing, invalid, or revoked. Check the following:- Header name: Must be
x-api-key(lowercase).AuthorizationorX-Api-Keywon’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.
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.balancefield) - Top up credits from the dashboard
- Use Estimate Extraction before running extractions to avoid surprises
Monitor Credits
Monitor slots are unlimited. Active instant monitors cost 21 credits per hour and require available credits while enabled.- 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}orDELETE /api/v1/monitors/keywords/{id} - Check current monitor billing:
GET /api/v1/accountshowsmonitorsUsedandmonitorBilling
429 Too Many Requests
You’ve exceeded the API rate limit. The API uses fixed windows per tier:Read
GET, HEAD, and OPTIONS share a limit of 60 requests per 1 second.Write
POST, PUT, and PATCH share a limit of 30 requests per 60 seconds.Delete
DELETE requests are limited to 15 requests per 60 seconds.- Respect
Retry-After; otherwise start at 1 second, add jitter, and stop after 3 retries. - Requests sent before the fixed window resets keep returning
429untilRetry-Afterelapses. - Check the
Retry-Afterheader 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.
502 Extraction Failing
The read service is temporarily unavailable. This is usually transient. Solutions:- Retry the request after 5-10 seconds
- Use exponential backoff (see Error Handling)
- If the error persists for more than 5 minutes, the read service may be experiencing an outage
/api/v1/x/*).
Common questions
Webhooks not arriving?
Webhooks can fail silently. Walk through this checklist:- Webhook is active: Verify
isActive: trueviaGET /api/v1/webhooks. Inactive webhooks don’t receive deliveries. - HTTPS required: HTTP endpoints are rejected. Your URL must start with
https://. - Response time: We recommend responding with
2xxwithin 10 seconds. Slow responses may be treated as failures. - Check deliveries: Call
GET /api/v1/webhooks/{id}/deliveriesto see delivery status, attempt count, and error messages. - Correlate source events: Call
GET /api/v1/events/{id}with the storedstreamEventId. - Local testing: If using ngrok or a tunnel, verify it’s running and the URL is current. Ngrok URLs change on restart (free plan).
- Event type mismatch: Your webhook must subscribe to the event types your monitors produce. A webhook listening for
tweet.newwon’t receivetweet.replyevents.
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
isActive: Confirm viaGET /api/v1/monitors/{id}thatisActiveistrue. 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
eventTypesarray 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
hasMorein the response. Older events may be on subsequent pages.
How do I replay stored monitor events?
CallGET /api/v1/events?monitorId={id}&limit=50 and 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 returns202 x_write_unconfirmed, the send was dispatched
but final confirmation is pending.
- Store
writeActionId,status,charged, andchargedCredits - 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
tweetIdonly after the status response confirms success
How do I check my usage?
CallGET /api/v1/account. The creditInfo object shows your balance:
creditInfo.balance: Remaining credits available for metered calls- When
balancereaches0, metered calls are rejected until credits are topped up or auto top-up triggers
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
402withno_subscription
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. It requires x-api-key or OAuth 2.1 and exposes explore plus xquik.- For docs search, add
https://docs.xquik.com/mcp. - For account actions, get your API key from the dashboard.
- Configure
https://xquik.com/mcpwith anx-api-keyheader or OAuth login.
- Claude Desktop, Claude Code, ChatGPT (via Agents SDK), Codex CLI, Cursor, VS Code, Windsurf, OpenCode
How do I export extraction results?
CallGET /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
Still stuck?
- Authentication: API key format, header requirements, and dual auth details.
- Error Handling: Error codes, retry strategies, and graceful degradation.
- Billing & Usage: Pricing, credits, and per-operation costs.