Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vibepeak.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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)
    }
  }
}
FieldDescription
codeMachine-readable error code for programmatic handling
messageHuman-readable description of the error
request_idUnique identifier for support reference
detailsAdditional context about the error (when available)

​
HTTP Status Codes

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

​
Error Codes Reference

​
Authentication Errors

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).
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

Status: 403 ForbiddenYour subscription plan doesn’t include API access. Only Plus, Pro and Max plans have API access.
{
  "error": {
    "code": "PLAN_NOT_ALLOWED",
    "message": "Your plan does not include API access. Please upgrade to Plus, Pro or Max.",
    "request_id": "req_xyz123",
    "details": {
      "current_plan": "Free",
      "required_credits": 10,
      "current_credits": 0
    }
  }
}
Solution: Upgrade your plan to Plus, Pro or Max.
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.
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.
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.
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

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

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

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
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. This also covers invalid enum values such as an unsupported orientation.
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).
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.
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.
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.
Narrated slideshow requests no longer return MIXED_ORIENTATIONS. Use the optional orientation field to request portrait or landscape output explicitly, or omit it and let the API auto-detect from the first image.
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.

​
Script Length Errors

The script field must fit a per-scene budget that scales with the number of images. Each image becomes a scene of roughly 3 seconds, so the script needs 65–85 characters per image to produce a video where the narration neither cuts off early nor leaves silence at the end.
ImagesMin charactersMax characters
16585
3195255
5325425
9585765
If you’d rather have us write the script, send generate_script instead — the budget check is skipped and the generated script is sized correctly automatically.
Status: 400 Bad RequestThe script is shorter than image_count × 65 characters. The narration would end before the video does, leaving silent frames.
{
  "error": {
    "code": "SCRIPT_TOO_SHORT",
    "message": "Script is too short for 3 image(s). Minimum 195 characters required (65 per scene), but got 134. Either lengthen the script or send fewer images.",
    "request_id": "req_xyz123",
    "details": {
      "script_length": 134,
      "min_length": 195,
      "max_length": 255,
      "image_count": 3,
      "chars_per_scene_min": 65,
      "chars_per_scene_max": 85
    }
  }
}
Solution: Either expand the script up to at least min_length characters, or remove images until image_count × 65 ≤ your script length.
Status: 400 Bad RequestThe script is longer than image_count × 85 characters. The narration would be rushed to fit within the video, harming TTS quality.
{
  "error": {
    "code": "SCRIPT_TOO_LONG",
    "message": "Script is too long for 3 image(s). Maximum 255 characters allowed (85 per scene), but got 400. Either shorten the script or send more images.",
    "request_id": "req_xyz123",
    "details": {
      "script_length": 400,
      "min_length": 195,
      "max_length": 255,
      "image_count": 3,
      "chars_per_scene_min": 65,
      "chars_per_scene_max": 85
    }
  }
}
Solution: Either trim the script down to at most max_length characters, or add more images until image_count × 85 ≥ your script length.
Status: 400 Bad RequestThe script contains characters that the TTS engine cannot process. Only letters, spaces, and basic punctuation (. , ! ? ¿ ¡ ; : ' " -) are allowed. Numbers must be written as words (e.g. “three” instead of “3”), and symbols like @, #, $, %, & are not permitted.
{
  "error": {
    "code": "SCRIPT_INVALID_CHARACTERS",
    "message": "Script contains characters not supported by text-to-speech: \"3\", \"$\".",
    "request_id": "req_xyz123",
    "details": {
      "invalid_characters": ["3", "$"]
    }
  }
}
Solution: Replace numbers with their word form and remove unsupported symbols.

​
Not Found Errors

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.
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.
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.
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

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).
Status: Returned in task status (not HTTP error). Sandbox only.A deliberately-failed sandbox task, returned when a request from a vpk_test_ key includes "test_scenario": "fail". It lets you exercise your error-handling code without spending credits. The same livemode: false field that appears on every sandbox response is also set on the task status.
{
  "task_id": "task_abc123xyz",
  "status": "failed",
  "livemode": false,
  "error": {
    "code": "TEST_MODE_SIMULATED_FAILURE",
    "message": "Simulated failure for test mode. No video was generated and no credits were used."
  }
}
Solution: This is the expected response for the fail test scenario — not a real failure. Treat it as a hand-rolled fixture for your error-handling path. Do not retry: the same test_scenario will keep returning the same error. See Test Mode → The test_scenario parameter for the other scenarios.
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.
Status: 400 Bad RequestOne or more source images are below the minimum resolution. VibePeak requires an HD floor on every source image: the long side must be at least 1280 px and the short side at least 720 px. Anything smaller produces visibly upscaled or blurry output.
{
  "error": {
    "code": "IMAGE_RESOLUTION_TOO_LOW",
    "message": "1 image(s) below the minimum resolution. Required: long side ≥ 1280px and short side ≥ 720px.",
    "request_id": "req_xyz123",
    "details": {
      "invalid_images": ["https://example.com/thumbnail.jpg"]
    }
  }
}
Solution: Re-upload the offending images at HD or higher. If your source (e.g. a CRM export) only exposes thumbnails, check whether the full-resolution variant is available at a different URL.

​
Service Errors

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.
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.
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.
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.
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 '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',
        'IMAGE_INACCESSIBLE',
        'IMAGE_RESOLUTION_TOO_LOW',
        'SCRIPT_TOO_SHORT',
        'SCRIPT_TOO_LONG',
        'SCRIPT_INVALID_CHARACTERS',
        'SSRF_BLOCKED',
        'TEST_MODE_SIMULATED_FAILURE'
      ];
      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:
  1. Request ID - Found in every error response
  2. Error code - The machine-readable error code
  3. Timestamp - When the error occurred
  4. Request details - The endpoint and parameters used
Email: [email protected]