Error Reference - STRATUS X1

Stratus returns OpenAI-compatible error responses with detailed error information.

Error Format

interface ErrorResponse {
  error: {
    message: string;        // Human-readable error message
    type: string;           // Error type/code
    param?: string;         // Parameter that caused error (if applicable)
    code: string;           // Error code
  }
}

HTTP Status Codes

Status	Meaning	Common Causes
`400`	Bad Request	Invalid parameters, malformed JSON
`401`	Unauthorized	Invalid or missing API key
`403`	Forbidden	API key lacks required permissions
`404`	Not Found	Invalid endpoint
`413`	Payload Too Large	Input exceeds size limits
`429`	Rate Limit Exceeded	Too many requests
`500`	Internal Server Error	Unexpected server error
`503`	Service Unavailable	Model not loaded or overloaded
`504`	Gateway Timeout	Request took too long

Error Types

invalid_model

Status: 400 The specified model name is invalid or not supported.

{
  "error": {
    "message": "Model 'stratus-x1ac-mega-gpt-4o' is not valid",
    "type": "invalid_model",
    "param": "model",
    "code": "invalid_model"
  }
}

Causes:

Typo in model name
Unsupported Stratus size (use: small, base, large, xl, huge)
Unsupported LLM
Missing LLM suffix for chat completions

Solution:

// Wrong
model: 'stratus-x1ac-mega-gpt-4o'  // "mega" doesn't exist

// Right
model: 'stratus-x1ac-small-gpt-4o'

model_not_loaded

Status: 503 The requested Stratus model is not loaded on the server.

{
  "error": {
    "message": "Model 'x1ac-huge' is not available",
    "type": "model_not_loaded",
    "code": "model_not_loaded"
  }
}

Causes:

Model size not preloaded on server
Server configuration excludes this model
Model loading failed

Solution:

Try a different model size (base/large usually available)
Contact support if the model should be available
Wait and retry if server is warming up

llm_provider_error

Status: 502 Error from the execution LLM provider (OpenAI, Anthropic, etc.).

{
  "error": {
    "message": "LLM provider error: Rate limit exceeded at OpenAI",
    "type": "llm_provider_error",
    "code": "llm_provider_error"
  }
}

Causes:

Downstream LLM service is down
Rate limits on LLM provider
Invalid LLM API key (server-side)

Solution:

Retry with exponential backoff
Try different execution LLM
Check Status Page

planning_failed

Status: 504 Stratus planning timed out or failed.

{
  "error": {
    "message": "Planning timed out after 30s",
    "type": "planning_failed",
    "code": "planning_failed"
  }
}

Causes:

Very long input sequences
Complex goal requiring extensive planning
Server overload

Solution:

Simplify the goal or break into steps
Reduce input length
Retry with smaller model size

authentication_error

Status: 401 API key is invalid or missing.

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "authentication_error"
  }
}

Causes:

API key not provided
API key is incorrect
API key has been revoked

Solution:

// Check your API key
const client = new OpenAI({
  baseURL: 'https://api.stratus.run/v1',
  apiKey: process.env.STRATUS_API_KEY  // Verify this is set
});

// Verify it starts with "stratus_sk_live_" or "stratus_sk_test_"
if (!apiKey.startsWith('stratus_sk_live_') && !apiKey.startsWith('stratus_sk_test_')) {
  console.error('Invalid API key format');
}

rate_limit

Status: 429 Request rate limit exceeded.

{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit",
    "code": "rate_limit"
  }
}

Rate limiting is not currently enforced. If you receive a 429, implement exponential backoff and retry.

Solution:

// Implement exponential backoff
async function callWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429) {
        const waitTime = Math.pow(2, i) * 1000;
        await new Promise(r => setTimeout(r, waitTime));
      } else {
        throw error;
      }
    }
  }
}

// Usage
const response = await callWithRetry(() =>
  client.chat.completions.create({...})
);

invalid_request_error

Status: 400 Request parameters are invalid.

{
  "error": {
    "message": "messages[0].role must be 'system', 'user', or 'assistant'",
    "type": "invalid_request_error",
    "param": "messages[0].role",
    "code": "invalid_request_error"
  }
}

Common Causes: Missing required field:

// Wrong
await client.chat.completions.create({
  model: 'stratus-x1ac-small-gpt-4o'
  // Missing messages!
});

// Right
await client.chat.completions.create({
  model: 'stratus-x1ac-small-gpt-4o',
  messages: [{ role: 'user', content: 'Hello' }]
});

Invalid message role:

// Wrong
messages: [{ role: 'admin', content: '...' }]

// Right
messages: [{ role: 'system', content: '...' }]

Empty messages array:

// Wrong
messages: []

// Right
messages: [{ role: 'user', content: 'Hello' }]

Error Handling Patterns

Basic Try-Catch

try {
  const response = await client.chat.completions.create({
    model: 'stratus-x1ac-small-gpt-4o',
    messages: [...]
  });
} catch (error) {
  console.error('API error:', error.status, error.message);
}

Comprehensive Error Handling

async function createChatCompletion(params) {
  try {
    return await client.chat.completions.create(params);
  } catch (error) {
    switch (error.status) {
      case 400:
        // Invalid request - fix parameters
        console.error('Invalid request:', error.message);
        throw new Error(`Invalid request: ${error.message}`);

      case 401:
        // Authentication failed - check API key
        console.error('Authentication failed');
        throw new Error('Invalid API key');

      case 429:
        // Rate limited - wait and retry with backoff
        const waitTime = 2000;
        console.log(`Rate limited. Retrying in ${waitTime}ms`);
        await new Promise(r => setTimeout(r, waitTime));
        return createChatCompletion(params);  // Retry

      case 500:
      case 503:
        // Server error - retry with backoff
        console.error('Server error, retrying...');
        await new Promise(r => setTimeout(r, 2000));
        return createChatCompletion(params);  // Retry once

      case 504:
        // Timeout - simplify or split request
        console.error('Request timed out');
        throw new Error('Request timed out. Try simplifying the goal.');

      default:
        console.error('Unexpected error:', error);
        throw error;
    }
  }
}

Retry with Exponential Backoff

async function withRetry<T>(
  fn: () => Promise<T>,
  options = {
    maxRetries: 3,
    initialDelay: 1000,
    maxDelay: 10000,
    retryableStatuses: [429, 500, 503]
  }
): Promise<T> {
  let lastError;
  let delay = options.initialDelay;

  for (let attempt = 0; attempt <= options.maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error;

      // Don't retry non-retryable errors
      if (!options.retryableStatuses.includes(error.status)) {
        throw error;
      }

      // Don't retry if this was the last attempt
      if (attempt === options.maxRetries) {
        break;
      }

      // Wait before retrying
      await new Promise(r => setTimeout(r, delay));

      // Exponential backoff
      delay = Math.min(delay * 2, options.maxDelay);
    }
  }

  throw lastError;
}

// Usage
const response = await withRetry(() =>
  client.chat.completions.create({...})
);

Circuit Breaker Pattern

class StratusClient {
  private failureCount = 0;
  private circuitOpen = false;
  private resetTime = 0;

  async chat(params) {
    // Check circuit breaker
    if (this.circuitOpen) {
      if (Date.now() < this.resetTime) {
        throw new Error('Circuit breaker open - too many failures');
      }
      // Try to close circuit
      this.circuitOpen = false;
      this.failureCount = 0;
    }

    try {
      const response = await client.chat.completions.create(params);
      this.failureCount = 0;  // Reset on success
      return response;
    } catch (error) {
      this.failureCount++;

      // Open circuit after 5 failures
      if (this.failureCount >= 5) {
        this.circuitOpen = true;
        this.resetTime = Date.now() + 60000;  // 1 minute
        console.error('Circuit breaker opened');
      }

      throw error;
    }
  }
}

Monitoring Errors

Log Error Rates

const errorCounts = {};

try {
  const response = await client.chat.completions.create({...});
} catch (error) {
  // Track error types
  errorCounts[error.code] = (errorCounts[error.code] || 0) + 1;

  // Log to monitoring service
  logger.error('Stratus API error', {
    code: error.code,
    status: error.status,
    message: error.message,
    model: params.model
  });
}

Alert on Critical Errors

const CRITICAL_ERRORS = ['authentication_error', 'model_not_loaded'];

try {
  const response = await client.chat.completions.create({...});
} catch (error) {
  if (CRITICAL_ERRORS.includes(error.code)) {
    // Alert on call
    await sendAlert({
      severity: 'critical',
      message: `Stratus API error: ${error.code}`,
      details: error.message
    });
  }
}

Best Practices

Always handle errors - Don’t let exceptions crash your application
Implement retries - Retry transient errors (429, 500, 503)
Log errors - Track error rates and patterns
Use circuit breakers - Prevent cascading failures
Validate input - Catch errors before API calls when possible
Have fallbacks - Degrade gracefully when Stratus is unavailable

Support

If you encounter persistent errors:

Check Status Page
Review API Reference for correct usage
Contact support at support@stratus.run
Include error details: status code, error type, timestamp

Next Steps

Chat Completions - Main API documentation
Quickstart - Integration guide
Status Page - Check service health

API Reference

​Error Format

​HTTP Status Codes

​Error Types

​invalid_model

​model_not_loaded

​llm_provider_error

​planning_failed

​authentication_error

​rate_limit

​invalid_request_error

​Error Handling Patterns

​Basic Try-Catch

​Comprehensive Error Handling

​Retry with Exponential Backoff

​Circuit Breaker Pattern

​Monitoring Errors

​Log Error Rates

​Alert on Critical Errors

​Best Practices

​Support

​Next Steps

Error Format

HTTP Status Codes

Error Types

invalid_model

model_not_loaded

llm_provider_error

planning_failed

authentication_error

rate_limit

invalid_request_error

Error Handling Patterns

Basic Try-Catch

Comprehensive Error Handling

Retry with Exponential Backoff

Circuit Breaker Pattern

Monitoring Errors

Log Error Rates

Alert on Critical Errors

Best Practices

Support

Next Steps