QWED integration troubleshooting

Debug QWED integration issues including invalid API keys, backend configuration errors, and unexpected verification failures.

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:
   • Visit https://qwedai.com/pricing
   • Contact sales for enterprise
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:
   • Visit https://github.com/QWED-AI/qwed-enterprise/actions
   • Verify latest deployment succeeded

---

Error Code Reference

Error Code	Meaning	Solution
AUTH_001	Invalid API key	Check/regenerate key
AUTH_002	Expired key	Renew API key
QUOTA_001	Quota exceeded	Upgrade plan
TIMEOUT_001	Request timeout	Increase timeout
VALIDATION_001	Invalid input	Check 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:
   • https://docs.qwedai.com

Community Support:

• 💬 GitHub Discussions
• 🐛 Report Bug

Enterprise Support:

• 📧 Email: [e-mail]
• 💼 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 [e-mail] with:

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