​

Troubleshooting Routes

​

Quick Diagnostics Checklist

✓ Route is enabled (check Routes page)
✓ Using correct tenant subdomain
✓ x-knoxcall-route header matches route name exactly
✓ API key is valid (if using API key auth)
✓ Client IP is whitelisted (if using IP auth)
✓ Backend is reachable from internet
✓ Check API logs for detailed error messages

​

Common HTTP Status Codes

​

404 Not Found

​

Possible Causes

# Wrong:
-H "x-knoxcall-route: My-Route"

# Correct:
-H "x-knoxcall-route: my-route"

1. Go to Routes → Find your route
2. Toggle Enabled to ON
3. Save

# Wrong:
https://wrong-subdomain.knoxcall.com

# Correct:
https://a1b2c3d4.yourcompany.knoxcall.com

​

Debug Steps

# 1. List all routes
curl https://api.knoxcall.com/routes \
  -H "Authorization: Bearer YOUR_API_KEY"

# 2. Verify route exists and is enabled
# 3. Check route name matches exactly

​

401 Unauthorized

​

Possible Causes

# Check your API key
-H "x-knoxcall-key: tk_abc123_xyz789..."

• Copy key again from dashboard
• Ensure no extra spaces or line breaks
• Verify key hasn’t been deleted
• Check key hasn’t expired

# Add API key header
-H "x-knoxcall-key: YOUR_API_KEY"

1. Check route settings
2. Match authentication method
3. Either provide API key OR ensure IP is whitelisted

​

Debug Steps

# 1. Verify API key format (should be 72 chars starting with tk_)
echo "YOUR_API_KEY" | wc -c

# 2. Test API key validity
curl https://api.knoxcall.com/auth/verify \
  -H "x-knoxcall-key: YOUR_API_KEY"

# 3. Check route authentication requirements

​

403 Forbidden

​

Possible Causes

1. Navigate to Clients → Add Client
2. Add your IP address
3. Go to route → Environment Clients tab
4. Assign client to appropriate environment

1. Edit route
2. Toggle Requires Clients to OFF
3. Test request
4. Re-enable after testing

1. Go to route → Environment Clients
2. Add your client to the environment
3. Save

HTTP/1.1 429 Too Many Requests
X-RateLimit-Remaining: 0
Retry-After: 3600

• Wait for rate limit to reset
• Request limit increase
• Optimize request frequency

​

Debug Steps

# 1. Check your public IP
curl https://api.ipify.org

# 2. Verify IP is in client list
# Go to Clients page → Search for your IP

# 3. Check client assignment
# Route → Environment Clients → Verify client is listed

​

500 Internal Server Error

​

Possible Causes

{
  "Authorization": "Bearer {{secret:missing_key}}"
}

1. Navigate to Secrets
2. Create the missing secret
3. Update route configuration

1. Check secret value format
2. Update if needed
3. Test route again

1. Edit route
2. Check JSON syntax in Header/Body Injection
3. Use online JSON validator
4. Save with valid JSON

​

Debug Steps

# 1. Check API logs
# Go to Logs → API Logs → Find your request
# Look for error details

# 2. Verify secrets exist
# Go to Secrets → Check all referenced secrets

# 3. Validate configuration JSON
# Copy Header/Body Injection JSON
# Validate at jsonlint.com

​

502 Bad Gateway

​

Possible Causes

# Try reaching backend directly
curl https://your-backend.com/health

• Start your backend server
• Verify backend is running
• Check backend logs

1. Edit route
2. Check Target Base URL
3. Verify URL is correct
4. Include protocol: https://
5. Test URL directly: curl https://your-backend.com

• Backend running on localhost
• Backend behind firewall
• Backend only accessible via VPN
• Private IP address used

• Deploy backend with public IP
• Open firewall rules for KnoxCall IPs
• Use VPN egress feature (Enterprise)

• Certificate expired
• Self-signed certificate
• Certificate domain mismatch

• Renew SSL certificate
• Use valid CA-signed certificate
• For testing: Disable SSL verification in route settings (not recommended for production)

• Check backend logs
• Ensure backend returns proper HTTP response
• Verify headers are correctly formatted

​

Debug Steps

# 1. Test backend directly
curl -v https://your-backend.com/endpoint

# 2. Check SSL certificate
openssl s_client -connect your-backend.com:443 -servername your-backend.com

# 3. Verify DNS resolution
nslookup your-backend.com
dig your-backend.com

# 4. Test from KnoxCall's perspective
# Use route testing tool in dashboard

​

504 Gateway Timeout

​

Possible Causes

1. Edit route
2. Increase Timeout setting
3. Recommended max: 120 seconds

• Optimize backend performance
• Add caching
• Use async processing for long operations

• Slow response times
• High CPU/memory usage
• Database connection pool exhausted

• Scale backend (add more instances)
• Optimize database queries
• Add caching layer
• Enable rate limiting

• Optimize SQL queries
• Add database indexes
• Increase database resources
• Implement query timeout

• Use closer region (Multi-region feature)
• Optimize network path
• Consider CDN for static content

​

Debug Steps

# 1. Measure backend response time
time curl https://your-backend.com/endpoint

# 2. Check backend metrics
# - CPU usage
# - Memory usage
# - Active connections
# - Database query time

# 3. Enable detailed logging on backend
# Log each processing step with timestamps

# 4. Increase timeout temporarily for testing
# Route settings → Timeout: 60s

​

Authentication Issues

​

”Invalid signature” errors

• Wrong signing secret
• Message format mismatch
• Timestamp too old/new
• Clock skew between client and server

// 1. Verify message format
const message = `${timestamp}.${method}.${path}.${JSON.stringify(body)}`;

// 2. Check timestamp is current
const now = Math.floor(Date.now() / 1000);
console.log('Current timestamp:', now);

// 3. Verify secret is correct
console.log('Using secret:', secret.substring(0, 10) + '...');

// 4. Log computed signature
console.log('Computed signature:', signature);

​

OAuth2 token expired

• Access token expired
• Refresh token revoked
• OAuth2 secret needs reauthorization

1. Go to Secrets → Select OAuth2 secret
2. Check token status
3. If expired, click Reauthorize
4. Complete OAuth2 flow again

​

Connection Issues

​

”Connection refused”

• Backend not running
• Wrong port number
• Firewall blocking connections

# 1. Check if backend is listening
netstat -an | grep YOUR_PORT

# 2. Test local connection
curl http://localhost:YOUR_PORT/health

# 3. Test from external IP
curl http://YOUR_PUBLIC_IP:YOUR_PORT/health

# 4. Check firewall rules
iptables -L -n

​

“DNS resolution failed”

• Domain doesn’t exist
• DNS not configured
• DNS propagation not complete

# 1. Verify domain exists
nslookup your-backend.com

# 2. Check DNS records
dig your-backend.com

# 3. Wait for DNS propagation (24-48 hours for new domains)

# 4. Use IP address temporarily
# Route → Target URL: https://203.0.113.50

​

“SSL handshake failed”

• Expired certificate
• Self-signed certificate
• Certificate hostname mismatch

# 1. Test SSL
openssl s_client -connect your-backend.com:443

# 2. Check certificate expiration
echo | openssl s_client -connect your-backend.com:443 2>/dev/null | openssl x509 -noout -dates

# 3. Verify certificate matches domain
echo | openssl s_client -connect your-backend.com:443 2>/dev/null | openssl x509 -noout -subject

​

Performance Issues

​

High latency

• Requests taking longer than expected
• Inconsistent response times

Total latency: 2,500ms
├─ KnoxCall processing: 50ms
├─ Network to backend: 150ms
├─ Backend processing: 2,200ms  ← Problem here!
└─ Network back: 100ms

• knoxcall_time: Time spent in KnoxCall
• backend_time: Time backend took to respond
• total_time: Total request time

• If backend_time is high: Optimize backend
• If network_time is high: Use closer region
• If knoxcall_time is high: Contact support

​

Intermittent failures

• Some requests succeed, others fail
• No consistent pattern

• Backend load balancer issues
• Database connection pool exhausted
• Memory leaks in backend
• Network instability

1. Check failure rate over time
2. Identify patterns (time of day, specific endpoints)
3. Review backend logs during failures
4. Monitor backend resource usage

​

Testing & Debugging Tools

​

Use API Logs

1. Go to Logs → API Logs
2. Find your request
3. Expand to see:
   • Full request headers/body
   • Full response headers/body
   • Error messages
   • Latency breakdown

​

Test in Dashboard

1. Go to Routes → Select route
2. Click Test Route
3. Configure request
4. See detailed response

​

Use verbose curl

curl -v https://a1b2c3d4.acme.knoxcall.com/api/test \
  -H "x-knoxcall-route: my-route" \
  -H "x-knoxcall-key: YOUR_KEY"

• DNS resolution
• Connection establishment
• SSL handshake
• Request headers sent
• Response headers received

​

Check Health Endpoint

# If your backend has a health endpoint
curl https://your-backend.com/health

# Expected:
HTTP/1.1 200 OK
{"status": "healthy"}

​

Getting Help

​

1. Gather Information

- Route name
- Tenant subdomain
- Error message
- Request timestamp
- Expected behavior
- Actual behavior
- Steps to reproduce

​

2. Check API Logs

1. Go to Logs → API Logs
2. Copy Request ID
3. Include in support ticket

​

3. Export Configuration

1. Go to Routes → Select route
2. Click Export
3. Attach to support ticket

​

4. Contact Support

• Email: [email protected]
• Chat: Click support icon in dashboard
• Phone: Available for Enterprise customers

​

Prevention Tips

​

1. Enable Health Checks

1. Edit route
2. Enable Health Checks
3. Set check interval: 60s
4. Set alert threshold

​

2. Set Up Alerts

Alert: Route Error Rate > 5%
Channels: Email, Slack

​

3. Use Staging Environment

1. Create staging environment
2. Test route changes in staging
3. Verify everything works
4. Deploy to production

​

4. Monitor Regularly

• Success rates
• Latency trends
• Error patterns
• Usage statistics

​

5. Keep Backend Logs

• HTTP request/response
• Processing time
• Error messages
• Stack traces

​

Next Steps