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

# Error Reference

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

## Error Format

```typescript theme={null}
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.

```json theme={null}
{
  "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:**

```typescript theme={null}
// 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.

```json theme={null}
{
  "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.).

```json theme={null}
{
  "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](https://status.stratus.run)

### planning\_failed

**Status:** `504`

Stratus planning timed out or failed.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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:**

```typescript theme={null}
// 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.

```json theme={null}
{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit",
    "code": "rate_limit"
  }
}
```

<Note>
  Rate limiting is not currently enforced. If you receive a `429`, implement exponential backoff and retry.
</Note>

**Solution:**

```typescript theme={null}
// 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.

```json theme={null}
{
  "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:**

```typescript theme={null}
// 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:**

```typescript theme={null}
// Wrong
messages: [{ role: 'admin', content: '...' }]

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

**Empty messages array:**

```typescript theme={null}
// Wrong
messages: []

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

## Error Handling Patterns

### Basic Try-Catch

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

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

## Support

If you encounter persistent errors:

1. Check [Status Page](https://status.stratus.run)
2. Review [API Reference](/docs/api-reference/introduction) for correct usage
3. Contact support at [support@stratus.run](mailto:support@stratus.run)
4. Include error details: status code, error type, timestamp

## Next Steps

* [Chat Completions](/docs/api-reference/chat-completions) - Main API documentation
* [Quickstart](/docs/quickstart) - Integration guide
* [Status Page](https://status.stratus.run) - Check service health