Troubleshooting

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

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

# 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

• Check your remaining balance via GET /api/v1/account (creditInfo.balance field)
• Top up credits from the dashboard
• Use Estimate Extraction before running extractions to avoid surprises

​

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

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

​

502 Extraction Failing

• 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

​

Common questions

​

Webhooks not arriving?

1. Webhook is active: Verify isActive: true via GET /api/v1/webhooks. Inactive webhooks don’t 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. 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 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?

​

Write action still 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?

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

​

Can I use the API without a 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

​

How do I connect an AI agent?

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.

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

​

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.