Troubleshooting

​

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 7 direct MPP operations, complete the MPP challenge or ask the user to confirm a guest wallet amount
• For the other 26 guest-eligible reads, authenticate or ask the user to confirm a guest wallet amount
• 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/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-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 and deliveryStatus: "active" via GET /api/v1/webhooks. Paused webhooks do not 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. Needs attention: If deliveryStatus is needs_attention, fix the receiver and call POST /api/v1/webhooks/{id}/resume. The receiver must pass a signed test before delivery resumes.
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 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?

• Guest wallet: Prepay 33 eligible GET routes through a confirmed $10-$250 USD Stripe-hosted Payment Link.
• MPP: Pay 7 fixed-price GET operations per request 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, and Qwen Code
• API-key fallback: affected Codex and Goose releases until their callback implementations preserve the RFC 9207 issuer value
• API-key only: Roo Code’s archived final release has no MCP OAuth provider
• No native MCP: Pi requires a separately installed and 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

​

Codex OAuth issuer validation error

Authorization server response missing required issuer: expected https://xquik.com

export XQUIK_API_KEY="xq_your_api_key_here"

[mcp_servers.xquik]
url = "https://xquik.com/mcp"
bearer_token_env_var = "XQUIK_API_KEY"

extensions:
  xquik:
    type: streamable_http
    name: xquik
    enabled: true
    uri: "https://xquik.com/mcp"
    headers:
      Authorization: "Bearer ${XQUIK_API_KEY}"
    env_keys:
      - XQUIK_API_KEY
    envs: {}

codex mcp add xquik-docs --url https://docs.xquik.com/mcp

goose session --with-streamable-http-extension https://docs.xquik.com/mcp

​

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.