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

# Workflows Error Handling

> Comprehensive guide to error handling for the Workflows API

This guide covers all possible error scenarios when working with the Workflows API, including HTTP status codes, error messages, causes, and resolution steps.

## Error Response Format

All workflow API errors follow a consistent JSON format:

```json theme={null}
{
  "error": "Error message describing what went wrong"
}
```

For streaming endpoints (like the query endpoint), errors are sent as Server-Sent Events:

```
event: error
data: {"error": "Error message describing what went wrong"}
```

## Authentication & Authorization Errors

### HTTP 401 - Unauthorized

**Missing API Key**

```json theme={null}
{
  "error": "Unauthorized"
}
```

* **Cause**: No Authorization header provided or invalid API key format
* **Resolution**: Include a valid API key in the Authorization header using HTTP Basic Authentication

**Invalid API Key**

```json theme={null}
{
  "error": "Unauthorized"
}
```

* **Cause**: API key is invalid or has been revoked
* **Resolution**: Verify your API key is correct and active in your Decisional account settings

## Validation Errors

### HTTP 400 - Bad Request

**Invalid Knowledge Engine ID**

```json theme={null}
{
  "error": "Invalid knowledge engine ID"
}
```

* **Cause**: The knowledge engine ID format is invalid or doesn't match expected pattern
* **Resolution**: Ensure the knowledge engine ID follows the format `ke_[alphanumeric]` and exists in your account

**Missing Required Fields**

```json theme={null}
{
  "error": "Key: 'WorkflowRequest.Name' Error:Field validation for 'Name' failed on the 'required' tag"
}
```

* **Cause**: Required fields like `name`, `query`, `type`, or `knowledge_engine_id` are missing
* **Resolution**: Include all required fields in your request body

**Invalid Model**

```json theme={null}
{
  "error": "Model unsupported-model not supported"
}
```

* **Cause**: The specified model name is not supported by the platform
* **Resolution**: Use a supported model name or omit the field to use the default model

**Model Not Enabled**

```json theme={null}
{
  "error": "Model Claude 3.5 Sonnet is not enabled"
}
```

* **Cause**: The specified model exists but is not enabled for your account
* **Resolution**: Contact support to enable the model or use a different enabled model

**Invalid JSON**

```json theme={null}
{
  "error": "invalid character '}' looking for beginning of object key string"
}
```

* **Cause**: Request body contains malformed JSON
* **Resolution**: Validate your JSON syntax and ensure proper formatting

## Knowledge Engine State Errors

### HTTP 400 - Bad Request

**Knowledge Engine Not Ready**

```json theme={null}
{
  "error": "knowledge engine is not ready, current status: processing"
}
```

* **Cause**: Knowledge engine is still processing uploaded documents and not ready for queries
* **Resolution**: Wait for the knowledge engine status to become "ready" before creating workflows
* **Check Status**: Use the GET `/api/v1/knowledge-engines/{id}` endpoint to monitor status

**No Active Data Sources**

```json theme={null}
{
  "error": "knowledge engine has no active data sources"
}
```

* **Cause**: Knowledge engine exists but has no uploaded documents or all data sources have been deleted
* **Resolution**: Upload at least one document to the knowledge engine before creating workflows

**Knowledge Engine Not Found**

```json theme={null}
{
  "error": "record not found"
}
```

* **Cause**: Knowledge engine with the specified ID doesn't exist or you don't have access to it
* **Resolution**: Verify the knowledge engine ID and ensure you have proper access permissions

## Processing Errors

### HTTP 500 - Internal Server Error

**RAG Service Failure**

```json theme={null}
{
  "error": "Failed to process query: connection timeout"
}
```

* **Cause**: Internal AI processing service is unavailable or experiencing issues
* **Resolution**: Retry the request after a few moments. If the issue persists, contact support

**Database Transaction Error**

```json theme={null}
{
  "error": "Failed to create workflow: database connection lost"
}
```

* **Cause**: Database connectivity issues during workflow creation
* **Resolution**: Retry the request. If the issue persists, contact support

**Document Retrieval Error**

```json theme={null}
{
  "error": "Failed to retrieve documents: vector database unavailable"
}
```

* **Cause**: Vector database service is temporarily unavailable
* **Resolution**: Retry the request after a few moments

## Streaming Query Errors

The `/api/v1/knowledge-engines/{id}/query` endpoint uses Server-Sent Events and can return errors during streaming:

**Connection Errors**

```
event: error
data: {"error": "knowledge engine is not ready, current status: processing"}
```

**Processing Errors**

```
event: error
data: {"error": "Failed to process query: model service unavailable"}
```

**Client Disconnection**

* **Cause**: Client disconnects before query completion
* **Resolution**: Ensure stable network connection and implement proper reconnection logic

## Error Handling Best Practices

### 1. Implement Retry Logic

For transient errors (5xx status codes), implement exponential backoff retry logic:

```javascript theme={null}
async function createWorkflowWithRetry(workflowData, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch('/api/v1/workflows', {
        method: 'POST',
        headers: {
          'Authorization': 'Basic ' + btoa(apiKey + ':'),
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(workflowData)
      });
      
      if (response.ok) {
        return await response.json();
      }
      
      if (response.status < 500) {
        // Client error, don't retry
        throw new Error(await response.text());
      }
      
      // Server error, retry with backoff
      if (attempt < maxRetries) {
        await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
      }
    } catch (error) {
      if (attempt === maxRetries) throw error;
    }
  }
}
```

### 2. Validate Knowledge Engine Status

Always check knowledge engine status before creating workflows:

```javascript theme={null}
async function ensureKnowledgeEngineReady(knowledgeEngineId) {
  const response = await fetch(`/api/v1/knowledge-engines/${knowledgeEngineId}`, {
    headers: {
      'Authorization': 'Basic ' + btoa(apiKey + ':')
    }
  });
  
  const ke = await response.json();
  
  if (ke.status !== 'ready') {
    throw new Error(`Knowledge engine not ready. Current status: ${ke.status}`);
  }
  
  if (ke.data_source_count === 0) {
    throw new Error('Knowledge engine has no data sources');
  }
  
  return ke;
}
```

### 3. Handle Streaming Errors

For the query endpoint, implement proper error handling for Server-Sent Events:

```javascript theme={null}
function queryKnowledgeEngine(knowledgeEngineId, query) {
  return new Promise((resolve, reject) => {
    const eventSource = new EventSource(`/api/v1/knowledge-engines/${knowledgeEngineId}/query`);
    
    eventSource.addEventListener('error', (event) => {
      const errorData = JSON.parse(event.data);
      eventSource.close();
      reject(new Error(errorData.error));
    });
    
    eventSource.addEventListener('done', (event) => {
      const result = JSON.parse(event.data);
      eventSource.close();
      resolve(result);
    });
    
    eventSource.onerror = (error) => {
      eventSource.close();
      reject(new Error('Connection error during streaming'));
    };
  });
}
```

## Common Resolution Steps

### Check Knowledge Engine Status

1. Use GET `/api/v1/knowledge-engines/{id}` to check status
2. Ensure status is "ready" before creating workflows
3. Verify `data_source_count > 0`

### Verify API Authentication

1. Check API key format: should be `dcl-[unique-identifier]`
2. Ensure proper Base64 encoding in Authorization header
3. Verify API key is active in your account settings

### Monitor Rate Limits

While not explicitly documented in error responses, implement reasonable request spacing to avoid potential rate limiting.

### Contact Support

For persistent 5xx errors or unexpected behavior, contact support with:

* Request ID (if available in response headers)
* Timestamp of the error
* Complete error message
* Steps to reproduce the issue