Troubleshooting Guide
Quick solutions for common issues, error codes, and debugging tips to help you resolve problems and optimize your Fusion AI integration.
Quick Fixes (Try These First)
Check API Key Format
Must start with 'sk-fusion-' and be included in Authorization header
Validate JSON Format
Use JSON validator to check request body syntax
Check Required Parameters
Include either 'prompt' or 'messages' in your request
Verify Endpoint URL
Use https://api.mcp4.ai/chat for chat completions
Check Content-Type Header
Set to 'application/json' for JSON requests
Test with Simple Request
Start with minimal request to isolate the issue
Common Issues by Category
Authentication Issues
❌ 401 Unauthorized Error
Cause: Invalid or missing API key
Solution: Verify your API key starts with 'sk-fusion-' and is correctly set in Authorization header
❌ 403 Forbidden Error
Cause: API key doesn't have required permissions
Solution: Check your account permissions or upgrade your plan
Rate Limits Issues
❌ 429 Too Many Requests
Cause: Exceeded rate limits for your plan
Solution: Implement exponential backoff or upgrade your plan for higher limits
❌ Slow Response Times
Cause: High load or complex requests
Solution: Use caching, optimize prompts, or distribute requests over time
Request Format Issues
❌ 400 Bad Request
Cause: Invalid JSON or missing required parameters
Solution: Validate JSON format and ensure 'prompt' or 'messages' parameter is included
❌ 422 Validation Error
Cause: Parameter values outside acceptable ranges
Solution: Check max_tokens, temperature, and other parameter limits
HTTP Error Codes Reference
| Code | Error | Description | Action |
|---|---|---|---|
| 400 | Bad Request | Invalid request format or parameters | Check JSON syntax and required fields |
| 401 | Unauthorized | Missing or invalid API key | Verify API key in Authorization header |
| 403 | Forbidden | Insufficient permissions | Check account permissions or upgrade plan |
| 404 | Not Found | Invalid endpoint or route | Verify API endpoint URL |
| 429 | Rate Limited | Too many requests | Implement rate limiting and retry logic |
| 500 | Internal Error | Server-side issue | Retry request or contact support |
| 503 | Service Unavailable | Temporary service outage | Wait and retry, check status page |
Debugging Tips
Check API Response Details
Every response includes metadata about the request processing
{
"response": "...",
"provider_used": "claude-3-opus",
"routing_reason": "Complex reasoning task",
"tokens_used": 234,
"cost": 0.00456,
"request_id": "req_abc123"
}Use Request IDs for Support
Include request_id when contacting support for faster resolution
// Save request ID for troubleshooting
const response = await fusion.chat({...});
console.log('Request ID:', response.request_id);Monitor Token Usage
Track token consumption to optimize costs and avoid limits
{
"tokens_used": 234,
"cost": 0.00456,
"cached": false,
"max_tokens_reached": false
}Performance Troubleshooting
Slow Response Times
High Token Usage
Testing & Validation Tools
🔧 API Testing
Use tools like Postman, curl, or HTTPie to test API requests independently
curl -X POST https://api.mcp4.ai/chat📊 Response Validation
Check response format, tokens_used, cost, and routing_reason fields
response.provider_used🔍 JSON Validation
Use online JSON validators to check request body syntax
jsonlint.comWhen to Contact Support
🆘 Immediate Support Needed
- • Persistent 500 or 503 errors across multiple requests
- • Billing or account access issues
- • Suspected security or data privacy concerns
- • Service outages affecting production systems
📝 Include in Support Requests
- • Request ID from the problematic API call
- • Timestamp when the issue occurred
- • Complete error message and HTTP status code
- • Sample request (remove sensitive data)
- • Expected vs actual behavior