Errors

The DesignCombo API uses standard HTTP status codes and returns detailed error messages to help you troubleshoot issues.

HTTP Status Codes

Code	Status	Description
`200`	OK	Request successful
`201`	Created	Resource created successfully
`400`	Bad Request	Invalid parameters or request format
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Insufficient permissions
`404`	Not Found	Resource not found
`409`	Conflict	Resource already exists
`422`	Unprocessable Entity	Validation failed
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server error
`502`	Bad Gateway	Service temporarily unavailable
`503`	Service Unavailable	Service maintenance

Error Response Format

All error responses follow a consistent format:

{
  "error": {
    "code": "invalid_parameter",
    "message": "The 'text' parameter is required",
    "details": {
      "parameter": "text",
      "reason": "missing_required_field",
      "suggestion": "Please provide a text parameter with your request"
    },
    "request_id": "req_1234567890abcdef"
  }
}

Field	Description
`code`	Machine-readable error code
`message`	Human-readable error message
`details`	Additional error context
`request_id`	Unique identifier for debugging

Common Error Codes

Authentication Errors

Error Code	Description	Solution
`invalid_api_key`	API key is invalid or expired	Check your API key and regenerate if needed
`missing_api_key`	No API key provided	Include `Authorization: Bearer YOUR_API_KEY` header
`insufficient_permissions`	API key lacks required permissions	Upgrade your plan or contact support

Resource Errors

Error Code	Description	Solution
`resource_not_found`	Requested resource doesn't exist	Check the resource ID or URL
`resource_already_exists`	Resource with same identifier exists	Use a different identifier or update existing resource
`resource_deleted`	Resource has been permanently deleted	Create a new resource

Validation Errors

Error Code	Description	Solution
`invalid_parameter`	Parameter value is invalid	Check parameter format and constraints
`missing_required_field`	Required parameter is missing	Include all required parameters
`file_too_large`	Uploaded file exceeds size limit	Compress or resize your file
`unsupported_format`	File format not supported	Convert to supported format
`invalid_url`	URL format is invalid	Check URL syntax and accessibility

Processing Errors

Error Code	Description	Solution
`processing_failed`	AI processing failed	Retry the request or contact support
`insufficient_credits`	Account has insufficient credits	Upgrade your plan or add credits
`service_unavailable`	Service is temporarily unavailable	Retry later or check status page
`timeout`	Request timed out	Retry with smaller files or shorter content

Error Handling Examples

JavaScript/Node.js

const handleApiError = async (response) => {
  if (!response.ok) {
    const errorData = await response.json();
    
    switch (response.status) {
      case 400:
        console.error('Bad request:', errorData.error.message);
        // Handle validation errors
        break;
      case 401:
        console.error('Authentication failed:', errorData.error.message);
        // Handle auth errors
        break;
      case 429:
        console.error('Rate limited:', errorData.error.message);
        // Implement retry logic
        break;
      case 500:
        console.error('Server error:', errorData.error.message);
        // Retry or contact support
        break;
      default:
        console.error('Unexpected error:', errorData.error.message);
    }
    
    throw new Error(errorData.error.message);
  }
  
  return response.json();
};

// Usage
try {
  const response = await fetch('https://api.designcombo.dev/v1/text-to-speech', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      text: 'Hello world',
      voiceId: '69nXRvRvFpjSXhH7IM5l'
    })
  });
  
  const data = await handleApiError(response);
  console.log('Success:', data);
} catch (error) {
  console.error('Request failed:', error.message);
}

Python

import requests
from typing import Dict, Any

def handle_api_error(response: requests.Response) -> Dict[str, Any]:
    if not response.ok:
        error_data = response.json()
        error_info = error_data.get('error', {})
        
        error_messages = {
            400: f"Bad request: {error_info.get('message')}",
            401: f"Authentication failed: {error_info.get('message')}",
            429: f"Rate limited: {error_info.get('message')}",
            500: f"Server error: {error_info.get('message')}"
        }
        
        error_message = error_messages.get(response.status_code, 
                                         f"Unexpected error: {error_info.get('message')}")
        
        raise requests.exceptions.RequestException(error_message)
    
    return response.json()

# Usage
try:
    response = requests.post(
        'https://api.designcombo.dev/v1/text-to-speech',
        headers={
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        },
        json={
            'text': 'Hello world',
            'voiceId': '69nXRvRvFpjSXhH7IM5l'
        }
    )
    
    data = handle_api_error(response)
    print('Success:', data)
except requests.exceptions.RequestException as e:
    print('Request failed:', str(e))

Retry Logic

Implement retry logic for transient errors:

const retryWithBackoff = async (apiCall, maxRetries = 3) => {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await apiCall();
    } catch (error) {
      const isRetryable = error.status >= 500 || error.status === 429;
      
      if (!isRetryable || attempt === maxRetries) {
        throw error;
      }
      
      const delay = Math.pow(2, attempt) * 1000;
      console.log(`Attempt ${attempt} failed. Retrying in ${delay}ms...`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
};

Debugging Tips

1. Check Request ID

Always log the request_id from error responses for debugging:

const errorData = await response.json();
console.log('Request ID:', errorData.error.request_id);

2. Validate Parameters

Before making requests, validate your parameters:

const validateTextToSpeechParams = (params) => {
  const errors = [];
  
  if (!params.text || params.text.trim().length === 0) {
    errors.push('Text parameter is required and cannot be empty');
  }
  
  if (params.text && params.text.length > 5000) {
    errors.push('Text parameter cannot exceed 5000 characters');
  }
  
  if (!params.voiceId) {
    errors.push('Voice ID is required');
  }
  
  return errors;
};

3. Check API Status

Monitor the API status page for known issues:

const checkApiStatus = async () => {
  try {
    const response = await fetch('https://status.designcombo.dev/api/v2/status.json');
    const status = await response.json();
    return status.status.indicator === 'operational';
  } catch {
    return true; // Assume operational if status check fails
  }
};

Getting Help

When you encounter errors:

1Check the error message for specific guidance
2Verify your request format matches the documentation
3Test with a simple request to isolate the issue
4Check the API status for known issues
5Contact support with the request ID for faster resolution

Need help debugging errors?

Include the request ID when contacting support
Test with the API playground to verify your request format
Check our status page for known issues
Review the error details for specific guidance