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
`422`	Unprocessable Entity - Request is well-formed but violates a business rule
`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 allow the requested operation. This code covers two distinct cases, distinguishable by message:

No API access at all: your plan doesn’t include API access. Only Plus, Pro, Max, and Enterprise plans have API access.
Family feature gated on your plan: your plan has API access, but working with families requires a higher plan. Creating, editing (adding, updating, regenerating, or removing a member), deleting, and using a family (as selected_family_id) all require Pro, Max, or Enterprise. Listing and reading families is open to every plan.

{
  "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": "none",
      "required_credits": 10,
      "current_credits": 0
    }
  }
}

{
  "error": {
    "code": "PLAN_NOT_ALLOWED",
    "message": "Families are available on the Pro, Max and Enterprise plans. Upgrade your plan to use this feature.",
    "request_id": "req_xyz123"
  }
}

Solution: Upgrade your plan. API access requires Plus or higher; creating, editing, deleting and using a family require Pro, Max or Enterprise (see Families).

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. This also covers invalid enum values such as an unsupported orientation.

INVALID_JSON

Status: 400 Bad RequestThe request body could not be parsed as JSON (e.g. a trailing comma, an unquoted key, or a truncated payload). This is checked before parameter validation, so you’ll see it instead of VALIDATION_ERROR when the body itself is malformed.

{
  "error": {
    "code": "INVALID_JSON",
    "message": "Request body is not valid JSON",
    "request_id": "req_xyz123"
  }
}

Solution: Verify the request body is valid JSON and that the Content-Type: application/json header is set. Serialize the body with your language’s JSON encoder rather than building it by hand.

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.

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.

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.

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.

Images	Min characters	Max characters
1	65	85
3	195	255
5	325	425
9	585	765

SCRIPT_TOO_SHORT

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.

SCRIPT_TOO_LONG

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.

SCRIPT_INVALID_CHARACTERS

Status: 400 Bad RequestThe script contains characters that the TTS engine cannot process. Numbers and symbols are allowed — text-to-speech reads them correctly. Only emojis and other non-speech characters (pictographs, control/zero-width characters) are rejected.

{
  "error": {
    "code": "SCRIPT_INVALID_CHARACTERS",
    "message": "Script contains characters not supported by text-to-speech: \"🏠\".",
    "request_id": "req_xyz123",
    "details": {
      "invalid_characters": ["🏠"]
    }
  }
}

Solution: Remove any emojis or other non-speech characters from the script.

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.

FAMILY_NOT_FOUND

Status: 404 Not FoundThe requested family doesn’t exist, or isn’t a preset, yours, or shared by your active organization. Returned by Get Family, Delete Family, the family member endpoints, and by selected_family_id on Create Living Property Video.

{
  "error": {
    "code": "FAMILY_NOT_FOUND",
    "message": "Family not found or not accessible with this API key.",
    "request_id": "req_xyz123"
  }
}

Solution: Verify the family ID with List Families, and confirm you have access to it.

FAMILY_MEMBER_NOT_FOUND

Status: 404 Not FoundThe index in the path doesn’t match any member in the family’s members array. Returned by Update Family Member, Regenerate Family Member Portrait, and Remove Family Member.

{
  "error": {
    "code": "FAMILY_MEMBER_NOT_FOUND",
    "message": "Member index is out of range for this family.",
    "request_id": "req_xyz123"
  }
}

Solution: Fetch the family with Get Family and use a 0-based index within the bounds of its members array.

Family Errors

FAMILY_NOT_READY

Status: 422 Unprocessable EntityThe family exists but isn’t ready (it’s still generating, pending_avatars, or failed). Returned when passing a non-ready family as selected_family_id, and by the family member endpoints when a generation is already in progress for the family: only one add, update, regenerate, or remove operation can run at a time.

{
  "error": {
    "code": "FAMILY_NOT_READY",
    "message": "The family is not ready yet: its member portraits are still generating. Poll the family until it is ready, then retry.",
    "request_id": "req_xyz123"
  }
}

The member endpoints return a different message for the same code when an edit is already running for that family:

{
  "error": {
    "code": "FAMILY_NOT_READY",
    "message": "Another generation is already in progress for this family. Poll the task until it finishes, then retry.",
    "request_id": "req_xyz123"
  }
}

Solution: It depends which of the two you got.

Initial generation (a family that has never finished): poll Get Family until status is ready.
An edit already in progress: poll the task_id that edit returned via Get Task, or poll the family until its status returns to ready. Get Task is the more direct option and is the only one that surfaces a failure reason.

FAMILY_MEMBER_LIMIT_EXCEEDED

Status: 422 Unprocessable EntityThe members array on Create Family has fewer than 1 or more than 6 entries, or Add Family Member would push the family past 6 members.

{
  "error": {
    "code": "FAMILY_MEMBER_LIMIT_EXCEEDED",
    "message": "A family must have between 1 and 6 members.",
    "request_id": "req_xyz123"
  }
}

Solution: Keep the family’s members between 1 and 6 entries; remove a member before adding a new one if you’re already at the limit.

FAMILY_MEMBER_MINIMUM

Status: 422 Unprocessable EntityRemove Family Member would leave the family with 0 members. A family must always have at least 1 member.

{
  "error": {
    "code": "FAMILY_MEMBER_MINIMUM",
    "message": "A family must keep at least one member.",
    "request_id": "req_xyz123"
  }
}

Solution: Delete the family instead if you no longer need any of its members.

FAMILY_LIMIT_REACHED

Status: 422 Unprocessable EntityYour account already has the maximum number of active custom families for its plan (5 on Pro, Max and Enterprise). Families shared with you by an organization don’t count against this limit.

{
  "error": {
    "code": "FAMILY_LIMIT_REACHED",
    "message": "You have reached the maximum number of families for your plan. Delete an existing family to create a new one.",
    "request_id": "req_xyz123"
  }
}

Solution: Delete a family you no longer need, then retry.

STORY_FAMILY_REQUIRED

Status: 400 Bad Requeststory_mode is true on Create Living Property Video but selected_family_id is missing. Story Mode is told through a family cast, so a family is required.

{
  "error": {
    "code": "STORY_FAMILY_REQUIRED",
    "message": "story_mode requires selected_family_id: the story is told through a family cast. Pass a family UUID or a preset slug.",
    "request_id": "req_xyz123"
  }
}

Solution: Pass a ready family’s UUID, or a preset slug, as selected_family_id.

STORY_ROOM_TYPE_REQUIRED

Status: 400 Bad Requeststory_mode is true but one or more images have no room_type. The planner needs a room for every image to order the scenes across the day.

{
  "error": {
    "code": "STORY_ROOM_TYPE_REQUIRED",
    "message": "story_mode requires a room_type on every image so the scenes can be planned.",
    "details": {
      "images_missing_room_type": [1, 4]
    },
    "request_id": "req_xyz123"
  }
}

Solution: Add a room_type to the images at the indices listed in details.images_missing_room_type.

STORY_PLAN_FAILED

Status: 502 Bad GatewayThe AI failed to produce a story plan. No credits were charged.

{
  "error": {
    "code": "STORY_PLAN_FAILED",
    "message": "Story planning failed. Please retry, or omit story_mode for a standard video.",
    "request_id": "req_xyz123"
  }
}

Solution: Retry the request, or omit story_mode for a standard video.

STORY_MODE_UNAVAILABLE

Status: 503 Service UnavailableStory Mode is temporarily unavailable on the rendering backend.

{
  "error": {
    "code": "STORY_MODE_UNAVAILABLE",
    "message": "Story Mode is temporarily unavailable. Retry later, or omit story_mode for a standard video.",
    "request_id": "req_xyz123"
  }
}

Solution: Retry later, or omit story_mode for a standard video.

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

TEST_MODE_SIMULATED_FAILURE

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.

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.

INVALID_WATERMARK_URL

Status: 400 Bad RequestThe elements_config.watermark.url is inaccessible or does not return an image. This is validated up front so a broken logo URL fails immediately instead of after the video has rendered. A common cause is a storage URL whose object has been deleted or moved — it returns application/json (“Object not found”) rather than the image.

{
  "error": {
    "code": "INVALID_WATERMARK_URL",
    "message": "Watermark image not accessible: HTTP 400",
    "request_id": "req_xyz123",
    "details": {
      "watermark_url": "https://example.com/logo.png"
    }
  }
}

Solution: Confirm the watermark URL is a publicly accessible HTTPS URL that returns an image/* content type (PNG, JPEG, WebP, SVG, or ICO).

IMAGE_RESOLUTION_TOO_LOW

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

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.

VOICE_REACTIVATION_UNAVAILABLE

Status: 503 Service UnavailableA cloned voice that had been idle for a long time is being restored, and the restore did not complete in time.Cloned voices you have not used for an extended period are archived automatically. The next request that uses one restores it transparently — you do not need to do anything, and the voice is not lost. This error means that restore could not be completed right now.

{
  "error": {
    "code": "VOICE_REACTIVATION_UNAVAILABLE",
    "message": "This voice is temporarily unavailable and could not be reactivated. Please try again in a few minutes.",
    "request_id": "req_xyz123"
  }
}

Solution: Retry in a few minutes. No credits are charged when this error is returned, and no task is created — so a retry is safe and will not double-charge you. If it persists for more than an hour, contact support.

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 '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;
}

import requests

def create_slideshow(images, api_key):
    response = requests.post(
        'https://api.vibepeak.ai/v1/real-estate/narrated-slideshow',
        headers={
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        },
        json={'images': images}
    )

    data = response.json()

    if not response.ok:
        error = data['error']
        code = error['code']
        message = error['message']
        request_id = error['request_id']
        details = error.get('details', {})

        if code in ['INVALID_API_KEY', 'MISSING_API_KEY']:
            raise Exception('Authentication failed. Check your API key.')

        if code == 'PLAN_NOT_ALLOWED':
            raise Exception(f"Upgrade required. Current plan: {details.get('current_plan')}")

        if code == 'INSUFFICIENT_CREDITS':
            raise Exception(f"Not enough credits. Have {details.get('current_credits')}, need {details.get('required_credits')}")

        if code in ['AVATAR_NOT_FOUND', 'AVATAR_ACCESS_DENIED']:
            raise Exception(f"Avatar error: {message}")

        if code in ['VOICE_NOT_FOUND', 'VOICE_ACCESS_DENIED', 'VOICE_EXPIRED']:
            raise Exception(f"Voice error: {message}")

        if code == 'CONCURRENCY_LIMIT_EXCEEDED':
            raise Exception(f"Rate limited. {details['in_flight']}/{details['limit']} tasks in progress.")

        if code == 'INVALID_JSON':
            hint = details.get('hint', '')
            raise Exception(f"Malformed JSON: {message}. {hint}")

        if code in ['VALIDATION_ERROR', 'IMAGE_INACCESSIBLE', 'IMAGE_TIMEOUT']:
            raise Exception(f"Invalid request: {message}")

        raise Exception(f"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:

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

Script Length Errors

Not Found Errors

Family 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

​Script Length Errors

​Not Found Errors

​Family 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

Script Length Errors

Not Found Errors

Family Errors

Task Errors

Service Errors

Handling Errors

Retry Strategy

Getting Support