> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwedai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:**

```python theme={null}
AuthenticationError: Invalid API key
```

**Solutions:**

1. **Check API key is correct:**
   ```bash theme={null}
   echo $QWED_API_KEY
   ```
2. **Verify key is active:**
   * Log into dashboard
   * Check API keys page
   * Regenerate if needed
3. **Check for whitespace:**
   ```python theme={null}
   api_key = os.getenv("QWED_API_KEY").strip()
   ```

***

## Verification failures

### Problem: Unexpected verification failures

**Symptoms:**

```python theme={null}
result.verified == False  # But should be True
```

**Debug steps:**

1. **Enable verbose mode:**
   ```python theme={null}
   client = QWEDClient(api_key="...", verbose=True)
   result = client.verify("2+2=4")
   ```
2. **Check trace:**
   ```python theme={null}
   result = client.verify("2+2=4", return_trace=True)
   print(json.dumps(result.trace, indent=2))
   ```
3. **Verify input format:**
   ```python theme={null}
   # 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:**
   ```python theme={null}
   # ❌ Slow
   for q in queries:
       result = client.verify(q)
   # ✅ Fast
   results = client.verify_batch([
       BatchItem(query=q) for q in queries
   ])
   ```
2. **Increase timeout:**
   ```python theme={null}
   client = QWEDClient(api_key="...", timeout=60)
   ```
3. **Check network latency:**
   ```bash theme={null}
   ping api.qwedai.com
   ```

***

## Quota issues

### Problem: "Quota exceeded"

**Symptoms:**

```python theme={null}
QuotaExceededError: API quota exceeded
```

**Solutions:**

1. **Check quota status:**
   ```python theme={null}
   status = client.get_quota_status()
   print(f"Used: {status.used}, Remaining: {status.remaining}")
   ```
2. **Upgrade plan:**
   * Visit [https://qwedai.com/pricing](https://qwedai.com/pricing)
   * Contact sales for enterprise
3. **Implement rate limiting:**
   ```python theme={null}
   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:**
   ```text theme={null}
   ❌ 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](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:**
   ```python theme={null}
   import logging
   logging.basicConfig(level=logging.DEBUG)
   ```
2. **Run test suite:**
   ```bash theme={null}
   python test_qwed_integration.py
   ```
3. **Search documentation:**
   * [https://docs.qwedai.com](https://docs.qwedai.com)

### Community support

* 💬 [GitHub Discussions](https://github.com/QWED-AI/qwed-verification/discussions)
* 🐛 [Report Bug](https://github.com/QWED-AI/qwed-verification/issues)

### Enterprise support

* 📧 Email: [support@qwedai.com](mailto: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](mailto:support@qwedai.com) with:

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