Skip to main content
Common issues, error codes, and solutions. If your problem isn’t covered here, contact support@xquik.com.
The API key is missing, invalid, or revoked. Check the following:
  • 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.
  • Session-only endpoint: The API Keys endpoints (/api/v1/api-keys/*) require session authentication (browser login), not API key auth. You cannot manage API keys via API key.
# 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
Your plan allows 1 monitor by default. Creating a second monitor returns:
{ "error": "monitor_limit_reached", "limit": 1 }
Solutions:
  • Delete an unused monitor to free a slot: DELETE /api/v1/monitors/{id}
  • Add more monitors from the dashboard billing page ($5/month each)
  • Check your current usage: GET /api/v1/account shows monitorsAllowed and monitorsUsed
Webhooks can fail silently. Walk through this checklist:
  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. Local testing: If using ngrok or a tunnel, verify it’s running and the URL is current. Ngrok URLs change on restart (free plan).
  6. 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.
See the Webhook Testing guide for a step-by-step local setup with ngrok.
If your monitor is active but no events appear:
  • 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.
You’ve exceeded the API rate limit. The API uses a 3-tier fixed window (60s):
TierMethodsLimit
ReadGET, HEAD, OPTIONS120 per 60s
WritePOST, PUT, PATCH30 per 60s
DeleteDELETE15 per 60s
Solutions:
  • Implement exponential backoff. Start at 1 second, double on each retry, max 5 retries.
  • 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.
See the Rate Limits guide for backoff code examples.
Call GET /api/v1/account. The currentPeriod object shows your usage:
{
  "currentPeriod": {
    "start": "2026-02-01T00:00:00.000Z",
    "end": "2026-03-01T00:00:00.000Z",
    "usagePercent": 15
  }
}
  • usagePercent: How much of your monthly quota has been consumed (0-100)
  • At 100, metered calls are rejected until the next billing period
The dashboard also displays usage graphically on the billing page.See Billing & Usage for monthly operation limits and usage scenarios.
Partially. Non-metered endpoints work without an active subscription:
  • Work without subscription: Monitors, events, webhooks, API keys, account management
  • Require subscription: Draws, extractions, X API lookups (tweets, users, follower checks) return 402 with no_subscription
Subscribe from the dashboard billing page to unlock metered endpoints. Access activates immediately after payment.
Xquik provides an MCP (Model Context Protocol) server for AI agent integration. 2 tools (explore + xquik) are available at https://xquik.com/mcp.Setup:
  1. Get your API key from the dashboard
  2. Configure your AI client with the MCP server URL and API key
  3. The agent authenticates via the x-api-key header, same as the REST API
Supported clients:
  • Claude Desktop, Claude Code, ChatGPT (via Agents SDK), Codex CLI, Cursor, VS Code, Windsurf, OpenCode
See the MCP Server overview for full setup instructions and the MCP Tools reference for tool details.
No active subscription or monthly usage quota exhausted. Possible error codes: no_subscription, subscription_inactive, usage_limit_reached. This affects metered endpoints (draws, extractions, tweet lookups, user lookups, follower checks).Solutions:
  • Check your remaining balance via GET /api/v1/account (usagePercent field)
  • Wait for the next billing period (quota resets automatically)
  • Use Estimate Extraction before running extractions to avoid surprises
Management endpoints (monitors, events, webhooks, API keys, account) are not affected and continue to work normally.
Metered calls return 402 with extra_usage_disabled when your included monthly allowance is consumed and extra usage is not enabled.Fix: Visit the dashboard subscription page and enable extra usage. Once enabled, metered calls continue beyond the included allowance instead of returning 402.
See the Extra Usage section for spending limits and tier details.
Metered calls return 402 with frozen even though extra usage was previously enabled.Cause: An overage payment failed. Extra usage freezes until the outstanding balance is resolved.Fix: Visit the dashboard subscription page to update your payment method. Once payment succeeds, extra usage resumes automatically.
Metered calls return 402 with overage_limit_reached when your accumulated overage hits your current spending limit.Cause: Each account has a spending limit that caps how much overage you can accumulate before the next invoice. Once the limit is reached, metered calls are rejected until the overage is paid.Fix:
  • Wait for the next overage invoice to be paid. Each successful payment raises your spending limit to the next tier.
  • Check your current spending limit and overage on the dashboard subscription page.
See the Spending Limits table for tier progression details.
The X data source 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 data source may be experiencing an outage
The same applies to draws and X data lookup endpoints (/api/v1/x/*).
Call GET /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
See Export Extraction for column details and code examples.

​
Still stuck?

Authentication

API key format, header requirements, and dual auth details.

Error Handling

Error codes, retry strategies, and graceful degradation.

Billing & Usage

Pricing, usage quotas, and monthly operation limits.