StateSet API Docs

Introduction

StateSet Cloud is our fully managed platform that provides scalable infrastructure, secure APIs, and comprehensive tools for building and deploying autonomous business operations. This guide will walk you through the initial setup and configuration of your StateSet Cloud environment.

Prerequisites

Before you begin, ensure you have:

A StateSet account (sign up at StateSet.com/sign-up)
Access to your email for verification
Basic understanding of REST APIs and authentication

Getting Started

Create a New Project

Navigate to the StateSet Cloud Dashboard and click the “New Project” button in the top right corner.Configure your project with:

Project Name: A unique identifier for your project
Environment: Choose between Development, Staging, or Production
Region: Select your preferred data center location for optimal performance

Create Your Organization

Set up your organization to manage team members and billing:

Click “New Organization” in the dashboard
Enter your organization details:
- Organization name
- Industry type
- Company size
Configure team settings and invite team members

Generate API keys

Create API keys to authenticate your applications:

Navigate to Settings > API keys
Click “New API key”
Configure key permissions:
- Read/Write access levels
- Scope restrictions (if needed)
- Expiration settings
Securely store your API key - it won’t be shown again

Core Features

Infrastructure Management

StateSet Cloud provides:

Auto-scaling: Automatically adjusts resources based on demand
Global CDN: Ensures fast response times worldwide
Database Management: Fully managed PostgreSQL with automatic backups
Event Streaming: Real-time event processing with Kafka

Security & Compliance

SOC 2 Type II Certified: Enterprise-grade security standards
Data Encryption: AES-256 encryption at rest and in transit
RBAC: Role-based access control for team management
Audit Logs: Complete activity tracking for compliance

Monitoring & Analytics

Real-time Dashboards: Monitor API usage, performance metrics, and costs
Custom Alerts: Set up notifications for important events
Log Management: Centralized logging with search and filtering

Environment Configuration

Development Environment

// .env.development
STATESET_API_KEY=your_development_api_key
STATESET_API_URL=https://api.StateSet.com/v1
STATESET_ENVIRONMENT=development

Production Environment

// .env.production
STATESET_API_KEY=your_production_api_key
STATESET_API_URL=https://api.StateSet.com/v1
STATESET_ENVIRONMENT=production
STATESET_LOG_LEVEL=error

Quick Integration Example

Here’s a simple example to verify your StateSet Cloud setup:

const { StateSetClient } = require('StateSet-node');

// Initialize the client
const client = new StateSetClient({
  apiKey: process.env.STATESET_API_KEY,
  environment: process.env.STATESET_ENVIRONMENT
});

// Test the connection
async function testConnection() {
  try {
    const health = await client.health.check();
    logger.info('Connection successful:', health);
    
    // Create a test order
    const order = await client.orders.create({
      customer_email: 'test@example.com',
      items: [{
        sku: 'TEST-001',
        quantity: 1,
        price: 99.99
      }]
    });
    
    logger.info('Test order created:', order.id);
  } catch (error) {
    logger.error('Connection failed:', error);
  }
}

testConnection();

Best Practices

API key Management

Never commit API keys to version control
Use environment variables for key storage
Rotate keys regularly
Use separate keys for different environments

Rate Limiting

Default rate limit: 1000 requests per minute
Implement exponential backoff for retries
Use webhook endpoints for async operations

Error Handling

try {
  const response = await client.orders.list();
  // Process response
} catch (error) {
  if (error.status === 429) {
    // Handle rate limiting
    await sleep(error.retryAfter * 1000);
  } else if (error.status >= 500) {
    // Handle server errors
    logger.error('Server error:', error.message);
  }
}

Support Resources

Documentation: docs.StateSet.com
API Reference: api.StateSet.com/reference
Community Forum: community.StateSet.com
Support Email: support@StateSet.com

Advanced Configuration

Rate Limiting and Retry Strategies

Implement robust retry logic to handle API rate limits and transient failures:

class StateSetApiClient {
  constructor(apiKey, options = {}) {
    this.apiKey = apiKey;
    this.maxRetries = options.maxRetries || 3;
    this.retryDelay = options.retryDelay || 1000;
    this.rateLimiter = new RateLimiter({
      tokensPerInterval: 100,
      interval: 'minute'
    });
  }

  async makeRequest(endpoint, options = {}) {
    let lastError;
    
    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
      try {
        // Check rate limit
        await this.rateLimiter.removeTokens(1);
        
        const response = await fetch(`${STATESET_API_URL}${endpoint}`, {
          ...options,
          headers: {
            'Authorization': `Bearer ${this.apiKey}`,
            'Content-Type': 'application/json',
            ...options.headers
          }
        });

        // Handle rate limit response
        if (response.status === 429) {
          const retryAfter = response.headers.get('Retry-After');
          const delay = retryAfter ? parseInt(retryAfter) * 1000 : this.calculateBackoff(attempt);
          
          console.warn(`Rate limited. Retrying after ${delay}ms...`);
          await this.sleep(delay);
          continue;
        }

        // Handle other errors
        if (!response.ok) {
          const error = await response.json();
          throw new StateSetApiError(error.message, response.status, error.code);
        }

        return await response.json();
        
      } catch (error) {
        lastError = error;
        
        // Don't retry on client errors (4xx)
        if (error.status >= 400 && error.status < 500 && error.status !== 429) {
          throw error;
        }
        
        // Calculate exponential backoff
        if (attempt < this.maxRetries) {
          const delay = this.calculateBackoff(attempt);
          console.warn(`Request failed, retrying in ${delay}ms...`, error.message);
          await this.sleep(delay);
        }
      }
    }
    
    throw lastError || new Error('Max retries exceeded');
  }

  calculateBackoff(attempt) {
    // Exponential backoff with jitter
    const baseDelay = this.retryDelay * Math.pow(2, attempt);
    const jitter = Math.random() * 1000;
    return Math.min(baseDelay + jitter, 30000); // Max 30 seconds
  }

  sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

// Custom error class for better error handling
class StateSetApiError extends Error {
  constructor(message, status, code) {
    super(message);
    this.name = 'StateSetApiError';
    this.status = status;
    this.code = code;
  }
}

Connection Pooling and Performance

Optimize API performance with connection pooling and request batching:

class StateSetBatchClient extends StateSetApiClient {
  constructor(apiKey, options = {}) {
    super(apiKey, options);
    this.batchQueue = [];
    this.batchSize = options.batchSize || 50;
    this.batchInterval = options.batchInterval || 100;
    this.startBatchProcessor();
  }

  // Queue requests for batch processing
  async batchRequest(operation, data) {
    return new Promise((resolve, reject) => {
      this.batchQueue.push({
        operation,
        data,
        resolve,
        reject,
        timestamp: Date.now()
      });
    });
  }

  startBatchProcessor() {
    setInterval(async () => {
      if (this.batchQueue.length === 0) return;
      
      // Process up to batchSize items
      const batch = this.batchQueue.splice(0, this.batchSize);
      
      try {
        const response = await this.makeRequest('/batch', {
          method: 'POST',
          body: JSON.stringify({
            operations: batch.map(item => ({
              operation: item.operation,
              data: item.data
            }))
          })
        });

        // Resolve individual promises
        batch.forEach((item, index) => {
          if (response.results[index].error) {
            item.reject(new Error(response.results[index].error));
          } else {
            item.resolve(response.results[index].data);
          }
        });
      } catch (error) {
        // Reject all promises in the batch
        batch.forEach(item => item.reject(error));
      }
    }, this.batchInterval);
  }
}

Troubleshooting

Common Issues and Solutions

Authentication Errors

Problem: Getting 401 Unauthorized errorsSolutions:

Verify your API key is correct and hasn’t expired
Check that you’re using the correct environment (dev/staging/prod)
Ensure the Authorization header format is correct: Bearer YOUR_API_KEY

// Validate API key format
if (!apiKey || !apiKey.startsWith('sk_')) {
  throw new Error('Invalid API key format. Keys should start with sk_');
}

Rate Limiting Issues

Problem: Receiving 429 Too Many Requests errorsSolutions:

Implement exponential backoff (see retry strategy above)
Use batch endpoints when processing multiple items
Cache frequently accessed data
Monitor your usage in the dashboard

// Track API usage
const usage = await client.usage.get({
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});
logger.info(`API calls this month: ${usage.totalCalls}`);

Network Timeouts

Problem: Requests timing out or taking too longSolutions:

Implement request timeouts
Use regional endpoints for better latency
Enable HTTP keep-alive for connection reuse

// Configure timeout
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 30000);

try {
  const response = await fetch(url, {
    signal: controller.signal,
    // Enable keep-alive
    keepalive: true
  });
} finally {
  clearTimeout(timeout);
}

Data Validation Errors

Problem: Getting 400 Bad Request errorsSolutions:

Validate data before sending
Check required fields and data types
Use TypeScript for compile-time validation

interface OrderData {
  customer_email: string;
  items: Array<{
    sku: string;
    quantity: number;
    price: number;
  }>;
}

function validateOrderData(data: any): data is OrderData {
  return (
    typeof data.customer_email === 'string' &&
    Array.isArray(data.items) &&
    data.items.every(item => 
      typeof item.sku === 'string' &&
      typeof item.quantity === 'number' &&
      typeof item.price === 'number'
    )
  );
}

Debug Mode

Enable debug mode to troubleshoot issues:

const client = new StateSetClient({
  apiKey: process.env.STATESET_API_KEY,
  debug: true, // Enables detailed logging
  logger: {
    info: (msg, data) => logger.info('[INFO]', msg, data);,
    warn: (msg, data) => console.warn('[WARN]', msg, data),
    error: (msg, data) => logger.error('[ERROR]', msg, data);
  }
});

// Log all requests and responses
client.on('request', (req) => {
  logger.info('Request:', {
    method: req.method,
    url: req.url,
    headers: req.headers
  });
});

client.on('response', (res) => {
  logger.info('Response:', {
    status: res.status,
    headers: res.headers,
    data: res.data
  });
});

Monitoring and Alerts

Set Up Health Checks

Monitor your StateSet Cloud integration health:

class StateSetHealthMonitor {
  constructor(client, options = {}) {
    this.client = client;
    this.checkInterval = options.checkInterval || 60000; // 1 minute
    this.alertThreshold = options.alertThreshold || 3;
    this.failureCount = 0;
  }

  start() {
    setInterval(async () => {
      try {
        const health = await this.checkHealth();
        
        if (!health.healthy) {
          this.failureCount++;
          
          if (this.failureCount >= this.alertThreshold) {
            await this.sendAlert({
              type: 'service_unhealthy',
              message: `StateSet API unhealthy for ${this.failureCount} consecutive checks`,
              details: health
            });
          }
        } else {
          this.failureCount = 0;
        }
        
        // Log metrics
        await this.logMetrics({
          timestamp: new Date(),
          healthy: health.healthy,
          latency: health.latency,
          services: health.services
        });
        
      } catch (error) {
        logger.error('Health check failed:', error);
        this.failureCount++;
      }
    }, this.checkInterval);
  }

  async checkHealth() {
    const start = Date.now();
    
    try {
      const response = await this.client.health.check();
      const latency = Date.now() - start;
      
      return {
        healthy: response.status === 'healthy',
        latency,
        services: response.services,
        timestamp: new Date()
      };
    } catch (error) {
      return {
        healthy: false,
        error: error.message,
        timestamp: new Date()
      };
    }
  }

  async sendAlert(alert) {
    // Integrate with your alerting system
    // Example: PagerDuty, Slack, email, etc.
    logger.error('ALERT:', alert);
  }

  async logMetrics(metrics) {
    // Send to your metrics system
    // Example: Datadog, CloudWatch, Prometheus
    logger.info('Metrics:', metrics);
  }
}

// Start monitoring
const monitor = new StateSetHealthMonitor(client);
monitor.start();

Next Steps

Now that you have your StateSet Cloud environment set up with robust error handling and monitoring:

Explore StateSet One

Learn how to implement autonomous order management

Build with StateSet ResponseCX

Create intelligent AI agents for customer interactions

API Best Practices

Deep dive into API patterns and optimization

Production Checklist

Ensure your integration is production-ready

​Introduction

​Prerequisites

​Getting Started

​Core Features

​Infrastructure Management

​Security & Compliance

​Monitoring & Analytics

​Environment Configuration

​Development Environment

​Production Environment

​Quick Integration Example

​Best Practices

​API key Management

​Rate Limiting

​Error Handling

​Support Resources

​Advanced Configuration

​Rate Limiting and Retry Strategies

​Connection Pooling and Performance

​Troubleshooting

​Common Issues and Solutions

​Debug Mode

​Monitoring and Alerts

​Set Up Health Checks

​Next Steps