Error Handling

Error Response Format

All API errors follow a consistent JSON format:

{
  "success": false,
  "message": "Error description",
  "code": "ERROR_CODE",
  "details": {
    "field": "Additional context"
  }
}

HTTP Status Codes

Status Code	Meaning	Common Causes
400	Bad Request	Invalid parameters, missing required fields
401	Unauthorized	Invalid or missing API key
403	Forbidden	Valid API key but insufficient permissions
404	Not Found	Resource doesn’t exist or you don’t have access
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error (rare)

Common Errors

Authentication Errors

401 - Missing API Key

Error:

{
  "success": false,
  "message": "API key is required",
  "code": "MISSING_API_KEY"
}

Solution:

// ❌ Wrong - Missing header
fetch('https://api.hooked.so/v1/avatar/list')

// ✅ Correct - Include API key
fetch('https://api.hooked.so/v1/avatar/list', {
  headers: {
    'x-api-key': 'your_api_key_here'
  }
})

401 - Invalid API Key

Error:

{
  "success": false,
  "message": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Solution:

Verify your API key is correct
Check you’re using the right environment (production vs development)
Regenerate your API key if needed at https://hooked.so/settings/api

403 - Subscription Required

Error:

{
  "success": false,
  "message": "Active subscription required",
  "code": "SUBSCRIPTION_REQUIRED"
}

Solution:

Upgrade your plan at https://hooked.so/settings/billing
Check your subscription status

Validation Errors

400 - Missing Required Fields

Error:

{
  "success": false,
  "message": "Missing required fields",
  "code": "VALIDATION_ERROR",
  "details": {
    "missing": ["script", "avatarId"]
  }
}

Solution:

// ❌ Wrong - Missing required fields
{
  "type": "class"
}

// ✅ Correct - All required fields
{
  "type": "class",
  "script": "Your video script here",
  "avatarId": "avatar_123",
  "voiceId": "voice_456"
}

400 - Invalid Field Value

Error:

{
  "success": false,
  "message": "Invalid aspect ratio",
  "code": "INVALID_VALUE",
  "details": {
    "field": "aspectRatio",
    "value": "16:9",
    "allowed": ["ratio_9_16", "ratio_16_9", "ratio_1_1"]
  }
}

Solution:

// ❌ Wrong - Invalid format
{
  "aspectRatio": "16:9"
}

// ✅ Correct - Use enum value
{
  "aspectRatio": "ratio_16_9"
}

400 - Script Too Long

Error:

{
  "success": false,
  "message": "Script exceeds maximum length",
  "code": "SCRIPT_TOO_LONG",
  "details": {
    "maxLength": 5000,
    "currentLength": 6500
  }
}

Solution: Split your script into multiple videos or reduce the length

Resource Errors

404 - Avatar Not Found

Error:

{
  "success": false,
  "message": "Avatar not found",
  "code": "AVATAR_NOT_FOUND"
}

Solution:

List available avatars: GET /api/v1/avatar/list
Verify the avatar ID exists and you have access to it
Check if it’s a custom avatar from another team

404 - Template Not Found

Error:

{
  "success": false,
  "message": "Template not found or unauthorized",
  "code": "TEMPLATE_NOT_FOUND"
}

Solution:

List your templates: GET /api/v1/template/list
Verify the template ID
Ensure the template belongs to your team

Rate Limiting

429 - Rate Limit Exceeded

Error:

{
  "success": false,
  "message": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 100,
    "window": "1 hour",
    "retryAfter": 3600
  }
}

Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705320000
Retry-After: 3600

Solution:

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      const waitTime = retryAfter ? parseInt(retryAfter) * 1000 : 60000;
      
      console.log(`Rate limited. Waiting ${waitTime}ms before retry...`);
      await new Promise(resolve => setTimeout(resolve, waitTime));
      continue;
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

Processing Errors

Video Generation Failed

Webhook Payload:

{
  "event": "project.failed",
  "projectId": "proj_123",
  "status": "failed",
  "message": "Avatar voice synthesis failed",
  "code": "VOICE_SYNTHESIS_ERROR"
}

Common Causes:

Script contains unsupported characters
Voice model temporarily unavailable
Audio processing timeout

Solution:

Check script for special characters
Try a different voice
Retry the request
Contact support if persists

Template Variable Mismatch

Error:

{
  "success": false,
  "message": "Template variables don't match",
  "code": "VARIABLE_MISMATCH",
  "details": {
    "expected": ["name", "company"],
    "provided": ["name"],
    "missing": ["company"]
  }
}

Solution:

// ❌ Wrong - Missing variable
{
  "templateId": "tpl_123",
  "scenes": [{
    "script": "Hi {{name}} from {{company}}",
    "variables": [
      { "key": "name", "value": "John" }
      // Missing 'company'
    ]
  }]
}

// ✅ Correct - All variables provided
{
  "templateId": "tpl_123",
  "scenes": [{
    "script": "Hi {{name}} from {{company}}",
    "variables": [
      { "key": "name", "value": "John" },
      { "key": "company", "value": "Acme Corp" }
    ]
  }]
}

Error Handling Patterns

Basic Error Handling

async function createVideo(data) {
  try {
    const response = await fetch('https://api.hooked.so/v1/project/create', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': process.env.HOOKED_API_KEY
      },
      body: JSON.stringify(data)
    });
    
    const result = await response.json();
    
    if (!response.ok) {
      throw new Error(`API Error: ${result.message}`);
    }
    
    return result;
    
  } catch (error) {
    console.error('Failed to create video:', error);
    throw error;
  }
}

Advanced Error Handling

class HookedAPIError extends Error {
  constructor(message, code, statusCode, details) {
    super(message);
    this.name = 'HookedAPIError';
    this.code = code;
    this.statusCode = statusCode;
    this.details = details;
  }
}

async function createVideo(data) {
  try {
    const response = await fetch('https://api.hooked.so/v1/project/create', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': process.env.HOOKED_API_KEY
      },
      body: JSON.stringify(data)
    });
    
    const result = await response.json();
    
    if (!response.ok) {
      throw new HookedAPIError(
        result.message,
        result.code,
        response.status,
        result.details
      );
    }
    
    return result;
    
  } catch (error) {
    if (error instanceof HookedAPIError) {
      // Handle API errors
      switch (error.code) {
        case 'INVALID_API_KEY':
          console.error('Please check your API key');
          break;
        case 'RATE_LIMIT_EXCEEDED':
          console.error('Rate limit hit, waiting before retry...');
          await new Promise(r => setTimeout(r, 60000));
          return createVideo(data); // Retry
        case 'VALIDATION_ERROR':
          console.error('Validation failed:', error.details);
          break;
        default:
          console.error('API error:', error.message);
      }
    } else {
      // Handle network errors
      console.error('Network error:', error);
    }
    
    throw error;
  }
}

Retry Logic with Exponential Backoff

async function makeRequestWithBackoff(url, options, maxRetries = 3) {
  let lastError;
  
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      const data = await response.json();
      
      // Success
      if (response.ok) {
        return data;
      }
      
      // Don't retry client errors (4xx except 429)
      if (response.status >= 400 && response.status < 500 && response.status !== 429) {
        throw new HookedAPIError(data.message, data.code, response.status, data.details);
      }
      
      // Retry server errors (5xx) and rate limits (429)
      lastError = new HookedAPIError(data.message, data.code, response.status, data.details);
      
      // Calculate backoff: 2^attempt * 1000ms (1s, 2s, 4s, ...)
      const backoffMs = Math.pow(2, attempt) * 1000;
      
      console.log(`Request failed, retrying in ${backoffMs}ms... (attempt ${attempt + 1}/${maxRetries})`);
      await new Promise(resolve => setTimeout(resolve, backoffMs));
      
    } catch (error) {
      if (error instanceof HookedAPIError && error.statusCode < 500) {
        // Don't retry client errors
        throw error;
      }
      lastError = error;
    }
  }
  
  throw lastError;
}

// Usage
try {
  const result = await makeRequestWithBackoff(
    'https://api.hooked.so/v1/project/create',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': process.env.HOOKED_API_KEY
      },
      body: JSON.stringify(videoData)
    }
  );
  console.log('Video created:', result);
} catch (error) {
  console.error('Failed after retries:', error);
}

Debugging Tips

Check API Key

Verify your API key is correct and active

# Test authentication
curl -H "x-api-key: your_key" \
  https://api.hooked.so/v1/avatar/list

Validate Request Body

Use a JSON validator to ensure your payload is valid

// Add logging
console.log('Request body:', JSON.stringify(data, null, 2));

Check Response

Log the full response to see what went wrong

const response = await fetch(url, options);
console.log('Status:', response.status);
console.log('Headers:', Object.fromEntries(response.headers));
const text = await response.text();
console.log('Body:', text);

Monitor Rate Limits

Check rate limit headers in responses

console.log('Rate Limit:', response.headers.get('X-RateLimit-Limit'));
console.log('Remaining:', response.headers.get('X-RateLimit-Remaining'));

Error Prevention Checklist

Before making API calls:

API key is set and valid
All required fields are included
Field values match expected types and formats
Avatar/Voice/Template IDs exist and are accessible
Script length is within limits (< 5000 characters)
Rate limits are being tracked
Webhook URL is publicly accessible (if used)
Error handling is implemented
Retry logic for transient errors

Getting Help

Support

Contact support for assistance

Discord Community

Get help from the community

GitHub Issues

Report bugs and issues

Next Steps

Webhooks

Set up webhooks for reliable notifications

Best Practices

Learn production-ready patterns

Getting Started

Core Concepts

AI Agents

Guides

Examples

Error Response Format

HTTP Status Codes

Common Errors

Authentication Errors

Validation Errors

Resource Errors

Rate Limiting

Processing Errors

Error Handling Patterns

Basic Error Handling

Advanced Error Handling

Retry Logic with Exponential Backoff

Debugging Tips

Error Prevention Checklist

Getting Help

Support

Discord Community

GitHub Issues

Next Steps

Webhooks

Best Practices

​Error Response Format

​HTTP Status Codes

​Common Errors

​Authentication Errors

​Validation Errors

​Resource Errors

​Rate Limiting

​Processing Errors

​Error Handling Patterns

​Basic Error Handling

​Advanced Error Handling

​Retry Logic with Exponential Backoff

​Debugging Tips

​Error Prevention Checklist

​Getting Help

Support

Discord Community

GitHub Issues

​Next Steps

Webhooks

Best Practices

Error Response Format

HTTP Status Codes

Common Errors

Authentication Errors

Validation Errors

Resource Errors

Rate Limiting

Processing Errors

Error Handling Patterns

Basic Error Handling

Advanced Error Handling

Retry Logic with Exponential Backoff

Debugging Tips

Error Prevention Checklist

Getting Help

Next Steps