Troubleshooting

This guide covers common issues you might encounter when using UniCraft and provides solutions to resolve them.

Common Issues

Authentication Issues

Invalid API Key

Problem: Getting “Invalid API key” errors

Symptoms:

HTTP 401 Unauthorized errors
“Invalid API key” error messages
Authentication failures

Solutions:

Check API Key Format

# Verify your API key format
echo $UNICRAFT_API_KEY
# Should start with 'uc_' for UniCraft keys

Verify API Key Validity

# Test API key
curl -H "Authorization: Bearer $UNICRAFT_API_KEY" \
     https://api.unicraft.com/v1/health

Check Environment Variables

# Ensure environment variable is set
env | grep UNICRAFT_API_KEY

Regenerate API Key
- Log into UniCraft dashboard
- Go to Settings → API Keys
- Generate a new API key
- Update your environment variables

Expired API Key

Problem: API key has expired

Symptoms:

“API key expired” error messages
Authentication failures after working previously

Solutions:

Check Key Expiration
- Log into UniCraft dashboard
- Check API key expiration date
- Generate a new key if expired

Set Up Key Rotation

# Enable automatic key rotation
export UNICRAFT_API_KEY_ROTATION_ENABLED=true
export UNICRAFT_API_KEY_ROTATION_INTERVAL=90

Provider Issues

Provider Not Available

Problem: Provider is not responding or unavailable

Symptoms:

“Provider unavailable” errors
Timeout errors
503 Service Unavailable responses

Solutions:

Check Provider Status

# Check provider health
curl -H "Authorization: Bearer $UNICRAFT_API_KEY" \
     https://api.unicraft.com/v1/providers/status

Test Provider Connection

# Test specific provider
curl -H "Authorization: Bearer $UNICRAFT_API_KEY" \
     https://api.unicraft.com/v1/providers/openai/test

Configure Failover

const failoverConfig = {
  enabled: true,
  fallback_providers: ["anthropic", "google"],
  retry_attempts: 3,
};

Check Provider API Keys

# Verify provider API keys
echo $OPENAI_API_KEY
echo $ANTHROPIC_API_KEY
echo $GOOGLE_API_KEY

Rate Limiting

Problem: Hitting rate limits from providers

Symptoms:

“Rate limit exceeded” errors
429 Too Many Requests responses
Intermittent failures

Solutions:

Implement Rate Limiting

const rateLimits = {
  requests_per_minute: 60,
  requests_per_hour: 1000,
  tokens_per_minute: 100000,
};

Use Multiple Providers

const providers = [
  { name: "openai", weight: 0.5 },
  { name: "anthropic", weight: 0.3 },
  { name: "google", weight: 0.2 },
];

Implement Retry Logic

const retryConfig = {
  retry_attempts: 3,
  retry_delay: 1000,
  retry_delay_multiplier: 2,
};

Monitor Usage

# Check usage statistics
curl -H "Authorization: Bearer $UNICRAFT_API_KEY" \
     https://api.unicraft.com/v1/usage

Model Issues

Model Not Available

Problem: Requested model is not available

Symptoms:

“Model not found” errors
“Model unavailable” messages
404 Not Found responses

Solutions:

Check Available Models

# List available models
curl -H "Authorization: Bearer $UNICRAFT_API_KEY" \
     https://api.unicraft.com/v1/models

Use Smart Routing

const response = await unicraft.chat.completions.create({
  model: "auto", // Let UniCraft choose the best model
  messages: messages,
});

Check Provider Configuration

# Verify provider models
curl -H "Authorization: Bearer $UNICRAFT_API_KEY" \
     https://api.unicraft.com/v1/providers

Use Alternative Models

const alternativeModels = ["gpt-3.5-turbo", "claude-3-haiku", "gemini-pro"];

Poor Model Performance

Problem: Model responses are poor quality or slow

Symptoms:

Low-quality responses
Slow response times
Inconsistent results

Solutions:

Optimize Prompts

// Better prompt structure
const prompt = `
You are an expert in [domain].
Please provide a detailed and accurate response to the following question:

Question: ${userQuestion}

Please ensure your response is:
- Accurate and factual
- Well-structured
- Comprehensive but concise
`;

Adjust Model Parameters

const response = await unicraft.chat.completions.create({
  model: "gpt-4",
  messages: messages,
  temperature: 0.7, // Adjust for creativity
  max_tokens: 1000, // Set appropriate limit
  top_p: 0.9,
});

Try Different Models

const models = ["gpt-4", "claude-3-sonnet", "gemini-pro"];
// Test different models for your use case

Use Quality-Optimized Routing

const routingConfig = {
  strategy: "quality_optimized",
  quality_threshold: 0.9,
};

Cost Issues

High Costs

Problem: Spending more than expected on AI requests

Symptoms:

High monthly bills
Cost alerts
Budget exceeded warnings

Solutions:

Set Cost Limits

const costLimits = {
  max_cost_per_request: 0.01,
  daily_cost_limit: 100.0,
  monthly_cost_limit: 2000.0,
};

Use Cost-Optimized Routing

const routingConfig = {
  strategy: "cost_optimized",
  max_cost_per_request: 0.005,
  quality_threshold: 0.8,
};

Implement Caching

const cacheConfig = {
  enabled: true,
  ttl: 3600, // Cache for 1 hour
  max_size: 1000, // MB
};

Monitor Usage

# Check cost breakdown
curl -H "Authorization: Bearer $UNICRAFT_API_KEY" \
     https://api.unicraft.com/v1/analytics/costs

Use Cheaper Models

const cheapModels = ["gpt-3.5-turbo", "claude-3-haiku", "gemini-pro"];

Unexpected Charges

Problem: Unexpected charges on your bill

Symptoms:

Higher than expected costs
Charges for unused services
Billing discrepancies

Solutions:

Review Usage Reports

# Get detailed usage report
curl -H "Authorization: Bearer $UNICRAFT_API_KEY" \
     https://api.unicraft.com/v1/analytics/usage

Check Cost Breakdown

# Get cost breakdown by provider/model
curl -H "Authorization: Bearer $UNICRAFT_API_KEY" \
     https://api.unicraft.com/v1/analytics/costs

Set Up Alerts

const alerts = [
  { threshold: 0.5, action: "email" },
  { threshold: 0.8, action: "slack" },
  { threshold: 1.0, action: "pause" },
];

Audit API Usage
- Check for unexpected API calls
- Review application logs
- Verify request patterns

Performance Issues

Slow Response Times

Problem: API requests are taking too long

Symptoms:

High response times
Timeout errors
Poor user experience

Solutions:

Optimize Requests

// Reduce max_tokens for faster responses
const response = await unicraft.chat.completions.create({
  model: "gpt-3.5-turbo", // Faster model
  messages: messages,
  max_tokens: 100, // Smaller response
});

Use Faster Models

const fastModels = ["gpt-3.5-turbo", "claude-3-haiku", "gemini-pro"];

Implement Caching

const cacheConfig = {
  enabled: true,
  ttl: 3600,
  compression: true,
};

Use Performance-Optimized Routing

const routingConfig = {
  strategy: "performance_optimized",
  response_time_limit: 2000,
};

Optimize Network
- Use CDN for static content
- Implement connection pooling
- Use HTTP/2

High Error Rates

Problem: Many requests are failing

Symptoms:

High error rates
Frequent failures
Unreliable service

Solutions:

Implement Retry Logic

const retryConfig = {
  retry_attempts: 3,
  retry_delay: 1000,
  exponential_backoff: true,
};

Use Circuit Breaker

const circuitBreaker = {
  enabled: true,
  failure_threshold: 5,
  recovery_timeout: 30000,
};

Monitor Error Patterns

# Check error analysis
curl -H "Authorization: Bearer $UNICRAFT_API_KEY" \
     https://api.unicraft.com/v1/analytics/errors

Implement Fallback

const fallbackConfig = {
  enabled: true,
  fallback_providers: ["anthropic", "google"],
  fallback_models: ["gpt-3.5-turbo", "claude-3-haiku"],
};

Configuration Issues

Invalid Configuration

Problem: Configuration errors preventing service from working

Symptoms:

Startup failures
Configuration validation errors
Service not responding

Solutions:

Validate Configuration

# Validate environment variables
./validate-config.sh

Check Configuration Format

// Ensure proper JSON format
const config = {
  apiKey: process.env.UNICRAFT_API_KEY,
  baseURL: process.env.UNICRAFT_BASE_URL,
  timeout: parseInt(process.env.UNICRAFT_TIMEOUT) || 30000,
};

Test Configuration

# Test configuration
curl -H "Authorization: Bearer $UNICRAFT_API_KEY" \
     https://api.unicraft.com/v1/health

Review Documentation
- Check configuration reference
- Verify required fields
- Test with minimal configuration

Environment Issues

Problem: Issues with environment setup

Symptoms:

Environment variable not found
Configuration not loading
Service not starting

Solutions:

Check Environment Variables

# List all UniCraft variables
env | grep UNICRAFT

Verify Environment Setup

# Check if variables are exported
echo $UNICRAFT_API_KEY
echo $OPENAI_API_KEY

Use Environment Files

# Create .env file
cat > .env << EOF
UNICRAFT_API_KEY=uc_1234567890abcdef
OPENAI_API_KEY=sk-1234567890abcdef
ANTHROPIC_API_KEY=sk-ant-1234567890abcdef
EOF

# Load environment
source .env

Check Docker/Kubernetes

# Verify environment in containers
env:
  - name: UNICRAFT_API_KEY
    valueFrom:
      secretKeyRef:
        name: unicraft-secrets
        key: api-key

Debugging Tools

Logging

Enable Debug Logging

# Set debug log level
export UNICRAFT_LOG_LEVEL=debug
export UNICRAFT_LOG_REQUESTS=true
export UNICRAFT_LOG_RESPONSES=true
export UNICRAFT_LOG_PERFORMANCE=true

View Logs

# View application logs
tail -f /var/log/unicraft.log

# View Docker logs
docker logs -f unicraft-container

# View Kubernetes logs
kubectl logs -f deployment/unicraft

Monitoring

Health Checks

# Check service health
curl https://api.unicraft.com/v1/health

# Check provider status
curl -H "Authorization: Bearer $UNICRAFT_API_KEY" \
     https://api.unicraft.com/v1/providers/status

Metrics

# Get performance metrics
curl -H "Authorization: Bearer $UNICRAFT_API_KEY" \
     https://api.unicraft.com/v1/analytics/metrics

# Get usage statistics
curl -H "Authorization: Bearer $UNICRAFT_API_KEY" \
     https://api.unicraft.com/v1/analytics/usage

Testing

API Testing

# Test basic functionality
curl -X POST \
  -H "Authorization: Bearer $UNICRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "auto", "messages": [{"role": "user", "content": "Hello"}]}' \
  https://api.unicraft.com/v1/chat/completions

Provider Testing

# Test specific provider
curl -H "Authorization: Bearer $UNICRAFT_API_KEY" \
     https://api.unicraft.com/v1/providers/openai/test

Getting Help

Self-Service Resources

Documentation
Community
Status Page
- UniCraft Status
- Provider Status

Contact Support

Email Support
- support@unicraft.com
- Include error messages and logs
- Provide reproduction steps
Priority Support
- Available for enterprise customers
- 24/7 support for critical issues
- Direct access to engineering team
Bug Reports
- GitHub Issues
- Include detailed reproduction steps
- Provide logs and error messages

Before Contacting Support

Check Documentation
- Review relevant documentation
- Check troubleshooting guides
- Verify configuration
Gather Information
- Error messages and logs
- Configuration details
- Reproduction steps
- Environment information
Try Common Solutions
- Restart service
- Check API keys
- Verify network connectivity
- Test with minimal configuration

Prevention

Best Practices

Monitoring
- Set up health checks
- Monitor error rates
- Track performance metrics
- Set up alerts
Configuration
- Use environment variables
- Validate configuration
- Test in staging environment
- Document setup
Error Handling
- Implement retry logic
- Use circuit breakers
- Handle failures gracefully
- Log errors properly
Security
- Rotate API keys regularly
- Use secure storage
- Monitor for unusual activity
- Implement access controls

Regular Maintenance

Weekly
- Review error logs
- Check performance metrics
- Monitor costs
- Update dependencies
Monthly
- Review configuration
- Update API keys
- Analyze usage patterns
- Optimize costs
Quarterly
- Security audit
- Performance review
- Capacity planning
- Disaster recovery testing

Next Steps

After resolving issues:

Document Solutions: Record solutions for future reference
Update Monitoring: Improve monitoring based on issues encountered
Prevent Recurrence: Implement measures to prevent similar issues
Share Knowledge: Share solutions with team members
Continuous Improvement: Regularly review and improve processes