X API troubleshooting for tweets, exports & webhooks

​

Error codes

​

401 Unauthenticated

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

# 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

• For account keys, check GET /api/v1/account and use only the advertised account payment action
• For guest keys, check guest wallet 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 to see the credit cost before running extractions

​

Monitor credits

{ "error": "insufficient_credits", "message": "Insufficient credits" }

• 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

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

​

502/503 Read service busy or unavailable

• 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)
• If the error continues for more than 5 minutes, the read service may have an outage

​

Common questions

​

Webhooks not arriving?

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?

• 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?

​

Write action still pending?

• 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?

{
  "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.

​

Can I use the API without a subscription?

• 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?

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.

• 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

​

MCP OAuth does not open or shows an unknown application

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.

• 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

​

How do I export extraction results?

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