> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwedai.tech/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, unexpected verification failures, and network connectivity problems.

## 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.tech/pricing](https://qwedai.tech/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.tech/integration/getting-started
   ✅ docs.qwedai.tech/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.tech](https://docs.qwedai.tech)

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


## Related topics

- [QWED UCP troubleshooting](/ucp/troubleshooting.md)
- [QWED Open Responses troubleshooting](/open-responses/troubleshooting.md)
- [QWED Legal troubleshooting](/legal/troubleshooting.md)
- [QWED Infra troubleshooting](/infra/troubleshooting.md)
- [QWED MCP troubleshooting](/mcp/troubleshooting.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.