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

# Best Practices

> Essential guidelines for using Electron Hub API effectively

Follow these best practices to get the most out of the Electron Hub API while optimizing for performance, cost, and reliability.

## Authentication & Security

### API Key Management

* **Environment Variables**: Store API keys in environment variables, never in code
* **Key Rotation**: Regularly rotate API keys for enhanced security
* **Separate Keys**: Use different keys for development, staging, and production
* **Monitoring**: Monitor API key usage and set up alerts for unusual activity

```bash theme={null}
# Good: Environment variable
export ELECTRONHUB_API_KEY="your_api_key_here"

# Bad: Hardcoded in source
const apiKey = "ek-1234567890abcdef"; // Never do this!
```

### Request Security

* **HTTPS Only**: Always use HTTPS endpoints
* **Input Validation**: Validate and sanitize all user inputs
* **Rate Limiting**: Implement client-side rate limiting
* **Error Handling**: Don't expose sensitive information in error messages

## Performance Optimization

### Request Optimization

* **Batch Requests**: Group multiple operations when possible
* **Streaming**: Use streaming for real-time applications
* **Caching**: Cache responses for repeated queries
* **Connection Pooling**: Reuse HTTP connections

```javascript theme={null}
// Good: Batch embedding requests
const embeddings = await fetch('/v1/embeddings', {
  method: 'POST',
  body: JSON.stringify({
    input: ['text1', 'text2', 'text3'], // Multiple inputs
    model: 'text-embedding-3-small'
  })
});

// Less efficient: Individual requests
for (const text of texts) {
  const embedding = await fetch('/v1/embeddings', {
    method: 'POST',
    body: JSON.stringify({
      input: text,
      model: 'text-embedding-3-small'
    })
  });
}
```

### Model Selection

* **Start Small**: Begin with cost-effective models for prototyping
* **Upgrade Selectively**: Use premium models only when necessary
* **Context Awareness**: Choose models based on context length requirements
* **Task Matching**: Match model capabilities to your specific use case

## Cost Management

### Token Optimization

* **Monitor Usage**: Track token consumption across all endpoints
* **Prompt Engineering**: Write efficient prompts that minimize tokens
* **Context Management**: Remove unnecessary context from conversations
* **Model Scaling**: Use appropriate models for different complexity levels

### Smart Caching

```javascript theme={null}
// Implement response caching
const cache = new Map();

async function getChatCompletion(messages, model) {
  const cacheKey = JSON.stringify({ messages, model });
  
  if (cache.has(cacheKey)) {
    return cache.get(cacheKey);
  }
  
  const response = await electronhub.chat.completions.create({
    messages,
    model
  });
  
  cache.set(cacheKey, response);
  return response;
}
```

## Error Handling

### Robust Error Management

* **Retry Logic**: Implement exponential backoff for transient errors
* **Graceful Degradation**: Provide fallbacks for API failures
* **Error Classification**: Handle different error types appropriately
* **User Experience**: Show meaningful error messages to users

```javascript theme={null}
async function makeAPICall(requestFn, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await requestFn();
    } catch (error) {
      if (error.status === 429) {
        // Rate limit - exponential backoff
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      
      if (error.status >= 500 && attempt < maxRetries) {
        // Server error - retry
        continue;
      }
      
      // Other errors or max retries reached
      throw error;
    }
  }
}
```

### Status Code Handling

* **200-299**: Success - process response
* **400-499**: Client errors - check request format
* **429**: Rate limited - implement backoff
* **500-599**: Server errors - retry with caution

## Prompt Engineering

### Chat Completions

* **Clear Instructions**: Be specific about what you want
* **System Messages**: Use system messages to set context and behavior
* **Few-shot Examples**: Provide examples for complex tasks
* **Format Specification**: Clearly specify desired output format

```javascript theme={null}
// Good: Clear, specific prompt
{
  "model": "gpt-3.5-turbo",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant that summarizes articles in exactly 3 bullet points."
    },
    {
      "role": "user", 
      "content": "Summarize this article: [article text]"
    }
  ]
}

// Less effective: Vague prompt
{
  "model": "gpt-3.5-turbo",
  "messages": [
    {
      "role": "user",
      "content": "Tell me about this article: [article text]"
    }
  ]
}
```

### Image Generation

* **Descriptive Prompts**: Include details about style, composition, and quality
* **Aspect Ratios**: Specify appropriate sizes for your use case
* **Style Consistency**: Use consistent terminology across related images
* **Quality Settings**: Choose appropriate quality levels for your needs

## Monitoring & Observability

### Usage Tracking

* **Token Metrics**: Monitor token usage per endpoint
* **Error Rates**: Track success/failure rates
* **Response Times**: Measure API latency
* **Cost Analysis**: Monitor spending across different models

### Logging Best Practices

```javascript theme={null}
// Structured logging example
const logger = {
  logAPICall: (endpoint, model, tokens, responseTime, status) => {
    console.log(JSON.stringify({
      timestamp: new Date().toISOString(),
      endpoint,
      model,
      tokens,
      responseTime,
      status,
      environment: process.env.NODE_ENV
    }));
  }
};

// Usage
const startTime = Date.now();
try {
  const response = await electronhub.chat.completions.create({
    model: 'gpt-3.5-turbo',
    messages: messages
  });
  
  logger.logAPICall(
    'chat/completions',
    'gpt-3.5-turbo',
    response.usage.total_tokens,
    Date.now() - startTime,
    'success'
  );
} catch (error) {
  logger.logAPICall(
    'chat/completions',
    'gpt-3.5-turbo',
    0,
    Date.now() - startTime,
    'error'
  );
}
```

## Development Workflow

### Testing Strategy

* **Unit Tests**: Test individual API interactions
* **Integration Tests**: Test complete workflows
* **Load Testing**: Verify performance under load
* **Error Scenarios**: Test failure conditions

### Environment Management

* **Development**: Use cheaper models and lower limits
* **Staging**: Mirror production setup for testing
* **Production**: Implement full monitoring and alerting

### Version Control

* **API Versioning**: Always specify API versions
* **Model Versioning**: Pin specific model versions for consistency
* **Configuration Management**: Version control all API configurations

## Compliance & Ethics

### Content Guidelines

* **Content Policy**: Ensure all content complies with usage policies
* **Moderation**: Use the Moderations API for user-generated content
* **Privacy**: Respect user privacy and data protection regulations
* **Transparency**: Be transparent about AI usage with users

### Responsible AI

* **Bias Awareness**: Be aware of potential model biases
* **Human Oversight**: Maintain human review for critical decisions
* **Fallback Plans**: Have non-AI alternatives for critical functions
* **User Control**: Give users control over AI interactions