Skip to main content

Troubleshooting Guide

Common issues and how to fix them.

Authentication Errors​

Problem: "Invalid API Key"​

Symptoms:

AuthenticationError: Invalid API key

Solutions:

  1. Check API key is correct:

    echo $QWED_API_KEY

  2. Verify key is active:

    • Log into dashboard
    • Check API keys page
    • Regenerate if needed

  3. Check for whitespace:

    api_key = os.getenv("QWED_API_KEY").strip()

Verification Failures​

Problem: Unexpected Verification Failures​

Symptoms:

result.verified == False  # But should be True

Debug steps:

  1. Enable verbose mode:

    client = QWEDClient(api_key="...", verbose=True)
    result = client.verify("2+2=4")

  2. Check trace:

    result = client.verify("2+2=4", return_trace=True)
    print(json.dumps(result.trace, indent=2))

  3. Verify input format:

    # Ensure input is well-formed
    query = "Calculate 2+2"  # Natural language
    # Not: "2 + 2"  # Might fail

Performance Issues​

Problem: Slow Response Times​

Symptoms: Response time > 5 seconds

Solutions:

  1. Use batch processing:

    # ❌ Slow
    for q in queries:
        result = client.verify(q)

    # ✅ Fast
    results = client.verify_batch([
        BatchItem(query=q) for q in queries
    ])

  2. Increase timeout:

    client = QWEDClient(api_key="...", timeout=60)

  3. Check network latency:

    ping api.qwedai.com

Quota Issues​

Problem: "Quota Exceeded"​

Symptoms:

QuotaExceededError: API quota exceeded

Solutions:

  1. Check quota status:

    status = client.get_quota_status()
    print(f"Used: {status.used}, Remaining: {status.remaining}")

  2. Upgrade plan:

  3. Implement rate limiting:

    from time import sleep

    for query in queries:
        result = client.verify(query)
        sleep(0.1)  # 10 req/sec max

Integration Issues​

Problem: Pages Still Showing 404​

症 Symptoms: "Page Not Found" on integration pages

Solutions:

  1. Use correct URL format:

    ❌ docs.qwedai.com/integration/getting-started
    ✅ docs.qwedai.com/docs/integration/getting-started

  2. Hard refresh:

    • Windows: Ctrl + Shift + R
    • Mac: Cmd + Shift + R

  3. Check deployment:

Error Code Reference​

Error CodeMeaningSolution
AUTH_001Invalid API keyCheck/regenerate key
AUTH_002Expired keyRenew API key
QUOTA_001Quota exceededUpgrade plan
TIMEOUT_001Request timeoutIncrease timeout
VALIDATION_001Invalid inputCheck input format

Getting Help​

Self-Service:​

  1. Check logs:

    import logging
    logging.basicConfig(level=logging.DEBUG)

  2. Run test suite:

    python test_qwed_integration.py

  3. Search documentation:

Community Support:​

Enterprise Support:​

  • 📧 Email: support@qwedai.com
  • 💼 Slack Connect (Enterprise customers)
  • 📞 Emergency Hotline (Enterprise Pro+)

Debug Checklist​

When troubleshooting:

  • Check error message carefully
  • Enable verbose/debug mode
  • Review logs
  • Test with simple query
  • Check network connectivity
  • Verify API key
  • Check quota status
  • Review recent code changes
  • Test in isolation
  • Search documentation

Still stuck? Contact support@qwedai.com with:

  • Error message
  • Code snippet
  • Steps to reproduce
  • QWED SDK version