Error Handling

The VibePeak API uses standard HTTP status codes and returns detailed error information to help you diagnose and resolve issues.

Error Response Format

All errors follow a consistent structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "request_id": "req_xyz123",
    "details": {
      // Additional context (optional)
    }
  }
}

Field	Description
`code`	Machine-readable error code for programmatic handling
`message`	Human-readable description of the error
`request_id`	Unique identifier for support reference
`details`	Additional context about the error (when available)

HTTP Status Codes

Status Code	Description
`200`	Success
`202`	Accepted - Task created successfully
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Plan doesn’t include API access
`404`	Not Found - Resource doesn’t exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Something went wrong

Error Codes Reference

Authentication Errors

INVALID_API_KEY

Status: 401 UnauthorizedThe provided API key is invalid or doesn’t exist.

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid.",
    "request_id": "req_xyz123"
  }
}

Solution: Check that your API key is correct and properly formatted (vpk_live_xxxxx or vpk_test_xxxxx).

MISSING_API_KEY

Status: 401 UnauthorizedNo API key was provided in the request.

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Include it in the Authorization header.",
    "request_id": "req_xyz123"
  }
}

Solution: Add the Authorization: Bearer vpk_live_xxxxx header to your request.

Authorization Errors

PLAN_NOT_ALLOWED

Status: 403 ForbiddenYour subscription plan doesn’t include API access. Only Plus and Pro plans have API access.

{
  "error": {
    "code": "PLAN_NOT_ALLOWED",
    "message": "Your plan does not include API access. Please upgrade to Plus or Pro.",
    "request_id": "req_xyz123",
    "details": {
      "current_plan": "Free",
      "required_credits": 10,
      "current_credits": 0
    }
  }
}

Solution: Upgrade your plan to Plus or Pro.

INSUFFICIENT_CREDITS

Status: 403 ForbiddenYour account doesn’t have enough credits for this operation.

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits. This operation requires 10 credits.",
    "request_id": "req_xyz123",
    "details": {
      "required_credits": 10,
      "current_credits": 5,
      "current_plan": "Plus"
    }
  }
}

Solution: Purchase more credits or wait for your monthly credit refresh.

AVATAR_ACCESS_DENIED

Status: 403 ForbiddenYou don’t have permission to use this avatar.

{
  "error": {
    "code": "AVATAR_ACCESS_DENIED",
    "message": "You do not have access to this avatar.",
    "request_id": "req_xyz123",
    "details": {
      "avatar_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }
}

Solution: Use a public avatar or one of your custom avatars. Custom avatars can only be accessed by their owner.

VOICE_ACCESS_DENIED

Status: 403 ForbiddenYou don’t have permission to use this voice.

{
  "error": {
    "code": "VOICE_ACCESS_DENIED",
    "message": "You do not have access to this voice.",
    "request_id": "req_xyz123",
    "details": {
      "voice_id": "cloned-voice-123"
    }
  }
}

Solution: Use a public voice or one of your cloned voices. Cloned voices can only be accessed by their owner.

VOICE_EXPIRED

Status: 403 ForbiddenThe cloned voice has expired.

{
  "error": {
    "code": "VOICE_EXPIRED",
    "message": "This voice has expired.",
    "request_id": "req_xyz123",
    "details": {
      "voice_id": "expired-voice-123"
    }
  }
}

Solution: Create a new cloned voice or use a public voice.

Internal Service Errors

AVATAR_URL_ERROR

Status: 500 Internal Server ErrorFailed to generate a secure URL for the avatar image.

{
  "error": {
    "code": "AVATAR_URL_ERROR",
    "message": "Failed to generate secure avatar URL",
    "request_id": "req_xyz123"
  }
}

Solution: This is a server-side issue. Retry your request. If the issue persists, contact support with the request_id.

Rate Limiting Errors

CONCURRENCY_LIMIT_EXCEEDED

Status: 429 Too Many RequestsYou’ve reached your concurrent task limit.

{
  "error": {
    "code": "CONCURRENCY_LIMIT_EXCEEDED",
    "message": "You have reached your concurrent task limit of 1. Please wait for existing tasks to complete.",
    "request_id": "req_xyz123",
    "details": {
      "limit": 1,
      "in_flight": 1,
      "plan": "Plus"
    }
  }
}

Solution: Wait for existing tasks to complete, or upgrade your plan for higher limits.

Validation Errors

INVALID_JSON

Status: 400 Bad RequestThe request body contains invalid JSON that cannot be parsed.

{
  "error": {
    "code": "INVALID_JSON",
    "message": "Request body contains invalid JSON. Please check your JSON syntax.",
    "request_id": "req_xyz123",
    "details": {
      "hint": "Ensure your request body is valid JSON with proper quotes, brackets, and commas."
    }
  }
}

Solution: Validate your JSON before sending. Common issues include:

Missing or extra commas
Unquoted property names
Single quotes instead of double quotes
Trailing commas in arrays or objects
Unescaped special characters in strings

VALIDATION_ERROR

Status: 400 Bad RequestThe request parameters are invalid.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "images must contain between 5 and 9 URLs",
    "request_id": "req_xyz123"
  }
}

Solution: Review the error message and fix the invalid parameters.

INVALID_AVATAR_ID

Status: 400 Bad RequestThe avatar ID format is invalid.

{
  "error": {
    "code": "INVALID_AVATAR_ID",
    "message": "Invalid avatar ID format.",
    "request_id": "req_xyz123"
  }
}

Solution: Ensure the avatar ID is a valid UUID format (e.g., a1b2c3d4-e5f6-7890-abcd-ef1234567890).

INVALID_VOICE_ID

Status: 400 Bad RequestThe voice ID format is invalid.

{
  "error": {
    "code": "INVALID_VOICE_ID",
    "message": "Invalid voice ID format.",
    "request_id": "req_xyz123"
  }
}

Solution: Use a valid voice ID from the List Voices endpoint or a cloned voice ID.

IMAGE_INACCESSIBLE

Status: 400 Bad RequestOne or more image URLs are not accessible.

{
  "error": {
    "code": "IMAGE_INACCESSIBLE",
    "message": "One or more images are not accessible.",
    "request_id": "req_xyz123",
    "details": {
      "invalid_images": ["https://example.com/missing.jpg"]
    }
  }
}

Solution: Ensure all image URLs are publicly accessible HTTPS URLs.

IMAGE_TIMEOUT

Status: 400 Bad RequestImage validation timed out.

{
  "error": {
    "code": "IMAGE_TIMEOUT",
    "message": "Image validation timed out. Please ensure all images are publicly accessible.",
    "request_id": "req_xyz123",
    "details": {
      "invalid_images": ["https://slow-server.com/image.jpg"]
    }
  }
}

Solution: Use images hosted on fast, reliable servers.

MIXED_ORIENTATIONS

Status: 400 Bad RequestImages have mixed orientations.

{
  "error": {
    "code": "MIXED_ORIENTATIONS",
    "message": "All images must have the same orientation (all portrait or all landscape).",
    "request_id": "req_xyz123",
    "details": {
      "invalid_images": [
        { "url": "https://example.com/img3.jpg", "orientation": "landscape" }
      ],
      "expected_orientation": "portrait"
    }
  }
}

Solution: Ensure all images are either portrait or landscape orientation. See our Image Requirements Guide for more details.

SSRF_BLOCKED

Status: 400 Bad RequestImage URL points to a private network.

{
  "error": {
    "code": "SSRF_BLOCKED",
    "message": "Image URL points to a private network which is not allowed.",
    "request_id": "req_xyz123"
  }
}

Solution: Use publicly accessible image URLs. Private/internal network URLs (localhost, 192.168.x.x, etc.) are not allowed.

Not Found Errors

USER_NOT_FOUND

Status: 404 Not FoundThe user account was not found.

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "User account not found.",
    "request_id": "req_xyz123"
  }
}

Solution: Ensure your API key is associated with a valid user account.

AVATAR_NOT_FOUND

Status: 404 Not FoundThe specified avatar was not found.

{
  "error": {
    "code": "AVATAR_NOT_FOUND",
    "message": "Avatar not found.",
    "request_id": "req_xyz123",
    "details": {
      "avatar_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }
}

Solution: Use a valid avatar ID from the public avatars list or your custom avatars.

VOICE_NOT_FOUND

Status: 404 Not FoundThe specified voice was not found.

{
  "error": {
    "code": "VOICE_NOT_FOUND",
    "message": "Voice not found.",
    "request_id": "req_xyz123",
    "details": {
      "voice_id": "invalid-voice-123"
    }
  }
}

Solution: Use a valid voice ID from the List Voices endpoint or a cloned voice ID.

TASK_NOT_FOUND

Status: 404 Not FoundThe requested task doesn’t exist.

{
  "error": {
    "code": "TASK_NOT_FOUND",
    "message": "Task not found.",
    "request_id": "req_xyz123"
  }
}

Solution: Verify the task ID is correct.

Task Errors

IMAGE_PROCESSING_FAILED

Status: Returned in task status (not HTTP error)One or more images couldn’t be processed.

{
  "error": {
    "code": "IMAGE_PROCESSING_FAILED",
    "message": "Failed to process image at index 2: Invalid image format"
  }
}

Solution: Ensure all images are accessible URLs with supported formats (JPEG, PNG, WebP).

INVALID_IMAGE_URL

Status: 400 Bad RequestOne or more image URLs are inaccessible, invalid, or point to private networks.

{
  "error": {
    "code": "INVALID_IMAGE_URL",
    "message": "Image validation failed",
    "request_id": "req_xyz123",
    "details": {
      "invalid_images": [
        { "index": 2, "url": "https://...", "reason": "Image is not accessible" }
      ]
    }
  }
}

Solution: Verify all image URLs are publicly accessible HTTPS URLs.

Service Errors

SERVICE_UNAVAILABLE

Status: 503 Service UnavailableThe video generation service is temporarily unavailable.

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Video generation service is temporarily unavailable. Please try again.",
    "request_id": "req_xyz123"
  }
}

Solution: Wait a few minutes and retry your request. Check status.vibepeak.ai for service updates.

SERVICE_TIMEOUT

Status: 504 Gateway TimeoutThe service request timed out.

{
  "error": {
    "code": "SERVICE_TIMEOUT",
    "message": "Video generation service is taking too long to respond. Please try again.",
    "request_id": "req_xyz123"
  }
}

Solution: Retry your request. If the issue persists, contact support.

SERVICE_ERROR

Status: 503 Service UnavailableAn internal service error occurred.

{
  "error": {
    "code": "SERVICE_ERROR",
    "message": "Failed to connect to video generation service",
    "request_id": "req_xyz123"
  }
}

Solution: Retry your request. If the issue persists, contact support with the request_id.

TTS_ERROR

Status: 503 Service UnavailableText-to-speech generation failed.

{
  "error": {
    "code": "TTS_ERROR",
    "message": "Text-to-speech service is temporarily unavailable",
    "request_id": "req_xyz123"
  }
}

Solution: Retry your request. The TTS service uses a circuit breaker that may temporarily block requests after repeated failures.

QUEUE_ERROR

Status: 503 Service UnavailableFailed to queue the video generation job.

{
  "error": {
    "code": "QUEUE_ERROR",
    "message": "Video generation service is temporarily unavailable. Please try again.",
    "request_id": "req_xyz123"
  }
}

Solution: Retry your request after a few seconds.

Handling Errors

async function createSlideshow(images, apiKey) {
  const response = await fetch('https://api.vibepeak.ai/v1/real-estate/narrated-slideshow', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ images })
  });

  const data = await response.json();

  if (!response.ok) {
    const { code, message, request_id, details } = data.error;

    switch (code) {
      case 'INVALID_API_KEY':
      case 'MISSING_API_KEY':
        throw new Error('Authentication failed. Check your API key.');

      case 'PLAN_NOT_ALLOWED':
        throw new Error(`Upgrade required. Current plan: ${details.current_plan}`);

      case 'INSUFFICIENT_CREDITS':
        throw new Error(`Not enough credits. Have ${details.current_credits}, need ${details.required_credits}`);

      case 'AVATAR_NOT_FOUND':
      case 'AVATAR_ACCESS_DENIED':
        throw new Error(`Avatar error: ${message}`);

      case 'VOICE_NOT_FOUND':
      case 'VOICE_ACCESS_DENIED':
      case 'VOICE_EXPIRED':
        throw new Error(`Voice error: ${message}`);

      case 'CONCURRENCY_LIMIT_EXCEEDED':
        throw new Error(`Rate limited. ${details.in_flight}/${details.limit} tasks in progress.`);

      case 'INVALID_JSON':
        throw new Error(`Malformed JSON: ${message}. ${details.hint || ''}`);

      case 'VALIDATION_ERROR':
      case 'MIXED_ORIENTATIONS':
      case 'IMAGE_INACCESSIBLE':
      case 'IMAGE_TIMEOUT':
        throw new Error(`Invalid request: ${message}`);

      default:
        throw new Error(`API error (${code}): ${message}. Request ID: ${request_id}`);
    }
  }

  return data;
}

Retry Strategy

For transient errors, implement exponential backoff:

async function withRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      // Don't retry authentication, authorization, or validation errors
      const nonRetryableCodes = [
        'INVALID_API_KEY',
        'MISSING_API_KEY',
        'PLAN_NOT_ALLOWED',
        'INSUFFICIENT_CREDITS',
        'AVATAR_NOT_FOUND',
        'AVATAR_ACCESS_DENIED',
        'VOICE_NOT_FOUND',
        'VOICE_ACCESS_DENIED',
        'VOICE_EXPIRED',
        'INVALID_JSON',
        'VALIDATION_ERROR',
        'MIXED_ORIENTATIONS',
        'IMAGE_INACCESSIBLE',
        'SSRF_BLOCKED'
      ];
      if (nonRetryableCodes.includes(error.code)) {
        throw error;
      }

      // Retry rate limits and server errors
      if (attempt < maxRetries - 1) {
        const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }

      throw error;
    }
  }
}

Never retry authentication (401) or validation (400) errors - they won’t succeed on retry.

Getting Support

When contacting support, include:

Request ID - Found in every error response
Error code - The machine-readable error code
Timestamp - When the error occurred
Request details - The endpoint and parameters used

Email: [email protected]

Getting Started

Core Concepts

Error Handling

Error Handling

Error Response Format

HTTP Status Codes

Error Codes Reference

Authentication Errors

Authorization Errors

Internal Service Errors

Rate Limiting Errors

Validation Errors

Not Found Errors

Task Errors

Service Errors

Handling Errors

Retry Strategy

Getting Support

Getting Started

Core Concepts

​Error Handling

​Error Response Format

​HTTP Status Codes

​Error Codes Reference

​Authentication Errors

​Authorization Errors

​Internal Service Errors

​Rate Limiting Errors

​Validation Errors

​Not Found Errors

​Task Errors

​Service Errors

​Handling Errors

​Retry Strategy

​Getting Support

Error Handling

Error Response Format

HTTP Status Codes

Error Codes Reference

Authentication Errors

Authorization Errors

Internal Service Errors

Rate Limiting Errors

Validation Errors

Not Found Errors

Task Errors

Service Errors

Handling Errors

Retry Strategy

Getting Support