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_...orAuthorization: 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 return401 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/accountand 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
401 or 402.Monitor credits
Monitor slots are unlimited. Active monitors cost 30 credits per hour. They 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. Poll the returned
statusUrluntil it returns404. - Check current monitor billing with
GET /api/v1/account, which showsmonitorsUsedandmonitorBilling
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 alimit needs that many results’ price left. A write needs its price plus 20 credits left. Other keys on the account keep working.- Raise or remove
monthlyBudgetCreditswith Update API key. The next call works. - Wait for the next UTC month, when the key’s spend starts again at 0.
- Compare
monthlySpentCreditsacross 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.
- 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. They push detected events without repeated event-list calls.
- Batch your logic. Fetch events once per minute instead of once per second.
502/503 Read service busy or unavailable
The read service is temporarily unavailable or busy. This is usually transient.Try these fixes.- Respect
Retry-Afterwhen present, then retry the request - If no
Retry-Afterheader 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
/api/v1/x/*.Common questions
Webhooks not arriving?
Webhook delivery can fail without a visible error. Check each item.- Webhook is active. Verify
isActive: trueanddeliveryStatus: "active"viaGET /api/v1/webhooks. Paused webhooks do not receive deliveries. - HTTPS required. Xquik rejects HTTP endpoints. Your URL must start with
https://. - Response time. Respond with
2xxwithin 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. - 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).
- Needs attention.
needs_attentionmeans 200 failed checks in a row. Xquik keeps retrying. Fix the receiver, then callPOST /api/v1/webhooks/{id}/resume. It starts sending waiting deliveries at once. - 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 these items.- 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 post content matching your event types. No posts means 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 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, andstatusUrl - Poll
statusUrlwhileterminalisfalse - Respect
Retry-After,pollAfterMs, andnextAction - Retry only when
safeToRetryistrue, using a newIdempotency-Key - Verify the result before retrying when
nextAction.typeisverify_result
How do I check my usage?
CallGET /api/v1/account. The creditInfo object shows your balance.creditInfo.balanceshows the remaining credits available for metered calls- At a
balanceof0, 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.
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.
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.- For docs search, add
https://docs.xquik.com/mcp. - For account actions, use a full API key or OAuth login. Prefer OAuth when the client supports browser authorization.
- For guest reads, activate a guest key through direct REST. Then authenticate MCP with that key.
- 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 mcprequire an upgrade or a tested adapter
MCP OAuth does not open or shows an unknown application
Use this checklist.- Enter
https://xquik.com/mcpas the exact server URL. - Remove any manually entered client ID or client secret unless your client requires preregistration.
- Remove and re-add the connector to restart OAuth discovery.
- Start login from the MCP client. Do not open
/api/auth/googledirectly. - Allow the browser to return to the client’s exact callback URL.
- 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
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?
CallGET /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
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.