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:

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "error": "Model gpt-5-turbo 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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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:

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:

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:

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