> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.twelvelabs.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server. # Error codes > Common API error codes and their meanings. Troubleshoot authentication, rate limit, and validation errors. This page lists the most common error messages you may encounter while using the platform. # General * `parameter_invalid` * The `{parameter}` parameter is invalid. * The following parameters are invalid: `{parameters}`. * The request contains some invalid parameters. * `parameter_not_provided` * The `{parameter}` parameter is required but was not provided. * The following required parameters were not provided: `{parameters}`. * Some required parameters are not provided. * `parameter_unknown` * The `{parameter}` parameter is unknown. * The following parameters are unknown: `{parameters}`. * The request contains some unknown parameters. * `resource_not_exist` * Resource with id `{resource_id}` does not exist in `{collection_name}`. * `api_key_invalid` * API Key is either invalid or expired. Please check your API key or generate a new one from the dashboard and try again. * `api_allowed_for_paid_plan` * API is allowed for paid plan only. Please upgrade to a paid plan to continue using the API. * `api_not_allowed` * API is not allowed to use. * `unauthorized` * Authentication failed. Please check your credentials and try again. * `region_not_allowed` * Twelve Labs API is not available in your region. Please refer to [https://twelvelabs.io/terms-of-use](https://twelvelabs.io/terms-of-use) * `request_canceled_or_timed_out` * Request canceled. * `too_many_requests` * You have exceeded the rate limit (`{rate_limit}`). Please try again later after `{retry_after}`. * `tags_not_allowed` * Tag `{tag}` is not allowed to use. Please remove it from the request. * The following tags are not allowed to be used: `{tags}`. Please remove these from the request. * `api_upgrade_required` * This endpoint is supported starting with version `{version}`. Your version is `{current_version}`. # The `/analyze` endpoint * `token_limit_exceeded` * The request exceeds the [context window](/v1.3/docs/concepts/models/pegasus#context-window) and cannot be processed. Reduce the prompt length, use a shorter video, or lower the `max_tokens` value. * `Live video streams are not supported. Please provide a URL that is not a live stream.` * The URL points to a live HLS stream. Only VOD manifests are supported. Provide the URL of a VOD manifest. * `output truncated: the generation reached the configured max_tokens. The partial output is returned; raise max_tokens if you need a longer response.` * The response reached the maximum response length in `general` mode. The platform returns the partial output and sets `finish_reason` to `"length"`. This message appears in the `error.message` field. * `output truncated: combined input and output tokens reached the model's context limit. The partial output is returned; consider reducing input size (shorter prompt, smaller video clip, fewer media bindings) or lowering max_tokens.` * The request reached the [context window](/v1.3/docs/concepts/models/pegasus#context-window) in `general` mode. The platform returns the partial output and sets `finish_reason` to `"length"`. This message appears in the `error.message` field. * `analysis failed: the time_based_metadata output reached the configured max_tokens before a complete result was produced. Raise max_tokens if it is below the per-model maximum; otherwise narrow the request (fewer segment_definitions or fields, a larger min_segment_duration, or a shorter analysis window).` * The response reached the maximum response length in `time_based_metadata` mode. The task fails with `status` set to `"failed"`, and no partial output is returned. This message appears in the `error.message` field. * `analysis failed: the time_based_metadata output reached the model's context limit (combined input and output tokens) before a complete result was produced. Narrow the request (fewer segment_definitions or fields, a larger min_segment_duration, a shorter analysis window, fewer media bindings) or lower max_tokens to leave more room for the input.` * The request reached the [context window](/v1.3/docs/concepts/models/pegasus#context-window) in `time_based_metadata` mode. The task fails with `status` set to `"failed"`, and no partial output is returned. This message appears in the `error.message` field. * `user_canceled` * An async analysis task was canceled through the task cancellation endpoint. The task has `status` set to `"canceled"`, and no result is returned. * `batch_canceled` * A queued analysis task was canceled because its batch was canceled. The task has `status` set to `"canceled"`, and no result is returned. * `batch_expired` * A queued analysis task was canceled because its batch expired. The task has `status` set to `"canceled"`, and no result is returned. * `batch_processing_timeout` * A processing analysis task failed after reaching its batch's processing deadline. The task has `status` set to `"failed"`, and no result is returned. * `index_not_supported_for_generate` * You can only summarize videos uploaded to an index with an engine from the Pegasus family enabled. # The `/analyze/tasks/{task_id}/cancel` endpoint * `task_owned_by_batch` * The task was created as part of a batch. Use the [`POST`](/v1.3/api-reference/analyze-videos/batch-analysis/cancel-batch) method of the `/analyze/batches/{batch_id}/cancel` endpoint instead. * `task_completed` * The task has completed. * `task_failed` * The task has failed. # The `/assets` endpoint * `content_type_invalid` * The content type `{content_type}` is not supported. Please use `multipart/form-data`. * `multipart_boundary_missing` * Multipart boundary is missing. Please provide the boundary in the `Content-Type` header. * `invalid_multipart` * Invalid multipart form. Please check your implementation and try again. * echo bind error * (Returns the raw bind error message) * echo validate error * (Returns a validator-generated message, for example: `Key: 'CreateAssetRequest.Method' Error:Field validation for 'Method' failed on the 'oneof' tag`) * `parameter_not_provided` * The `file` parameter is required but was not provided. `file` is required when `method` is `direct`. * The `url` parameter is required but was not provided. `url` is required when `method` is `url`. * `parameter_invalid` * The `method` parameter is invalid. To upload in parts, use the `/assets/multipart-uploads` endpoint. * The `file` parameter is invalid. Unable to process the uploaded file. Please try uploading again. * The `file` parameter is invalid. Unsupported asset type: `{asset_type}`. * The `image` parameter is invalid. Image dimensions `{current_dimensions}` are below the minimum `{minimum_dimensions}`. * The `image` parameter is invalid. Invalid image file. Please check the format and dimensions. * `media_url_unsupported_format` * The file at the provided URL is not a supported media format. Detected format: `{detected_format}`. Please provide a valid asset file. * `media_url_not_accessible` * Cannot access the media URL `{url}`. The server responded with an error. Please verify the URL is correct and publicly accessible. * `media_url_file_broken` * Cannot read the media file at the specified URL. Please verify the file is valid and try again. * `media_filesize_too_large` * The media file is too large. Please upload a file smaller than `{maximum_size}`. The current size is `{current_size}`. * `video_file_broken` * Unable to process video file. Please check if the file is valid and try again. * `video_file_live` * Live video streams are not supported. Please provide a URL that is not a live stream. * `video_resolution_too_low` * The resolution of the video is too low. Please upload a video with a resolution between `{minimum_resolution}` and `{maximum_resolution}`. Current resolution is `{current_resolution}`. * `video_resolution_too_high` * The resolution of the video is too high. Please upload a video with a resolution between `{minimum_resolution}` and `{maximum_resolution}`. Current resolution is `{current_resolution}`. * `video_resolution_invalid_aspect_ratio` * The aspect ratio of the video is invalid. Please upload a video with an aspect ratio between 1:1 and `{maximum_aspect_ratio}`. Current resolution is `{current_resolution}`. * `video_duration_too_short` * The video is too short. Please use a video with a duration of at least `{minimum_duration}` seconds. Current duration is `{current_duration}` seconds. * `video_duration_too_long` * The video is too long. Please use a video with a duration between `{minimum_duration}` and `{maximum_duration}` seconds. Current duration is `{current_duration}` seconds. * `video_filesize_too_large` * The video is too large. Please use a video with a size less than `{maximum_size}`. The current size is `{current_size}`. * `audio_file_broken` * Unable to process audio file. Please check if the file is valid and try again. * `audio_duration_too_short` * The audio is too short. Please use an audio file with a duration of at least `{minimum_duration}` seconds. Current duration is `{current_duration}` seconds. * `audio_duration_too_long` * The audio is too long. Please use an audio file with a duration between `{minimum_duration}` and `{maximum_duration}` seconds. Current duration is `{current_duration}` seconds. * `audio_filesize_too_large` * The audio is too large. Please use an audio file with a size less than `{maximum_size}`. The current size is `{current_size}`. * `audio_format_unsupported` * The audio format `{format}` is not supported. Please use one of the following formats: `{supported_formats}`. * `asset_transcription_not_found` * Transcription for asset `{asset_id}` does not exist. * `resource_not_exists` * The requested asset with the identifier `{asset_id}` does not exist. # The `/embed` endpoint * `parameter_invalid` * The `text` parameter is invalid. The text token length should be less than or equal to 77. * The `text_truncate` parameter is invalid. You should use one of the following values: `none`, `start`, `end`. # The `/embed/tasks` endpoint * `parameter_invalid` * The `video_clip_length` parameter is invalid. `video_clip_length` should be within 2-10 seconds long * The `video_end_offset_sec` parameter is invalid. `video_end_offset_sec` should be greater than `video_start_offset_sec` # The `/embed/tasks/{task-id}/status` endpoint * `parameter_invalid` * The `task_id` parameter is invalid. `task_id` value is invalid # The `/indexes` endpoint * `index_option_cannot_be_changed` * Index option cannot be changed. Please remove index\_options parameter and try again. If you want to change index option, please create new index. * `index_engine_cannot_be_changed` * Index engine cannot be changed. Please remove engine\_id parameter and try again. If you want to change engine, please create new index. * `index_name_already_exists` * Index name `{index_name}` already exists. Please use another unique name and try again. # The `/search` endpoint * `search_option_not_supported` * Search option `{search_option}` is not supported for index `{index_id}`. Please use one of the following search options: `{supported_search_option}`. * `search_option_combination_not_supported` * Search option `{search_option}` is not supported with `{other_combination}`. * `search_filter_invalid` * Filter used in search is invalid. Please use the valid filter syntax by following filtering documentation. * `search_page_token_expired` * The token that identifies the page to be retrieved is expired or invalid. You must make a new search request. Token: `{next_page_token}`. * `index_not_supported_for_search`: * You can only perform search requests on indexes with an engine from the Marengo family enabled. # The `/summarize` endpoint * `token_limit_exceeded` * The request exceeds the [context window](/v1.3/docs/concepts/models/pegasus#context-window) and cannot be processed. Reduce the prompt length, use a shorter video, or lower the `max_tokens` value. # The `/tasks` endpoint * `video_resolution_too_low` * The resolution of the video is too low. Please upload a video with resolution between 360x360 and 5184x2160. Current resolution is `{current_resolution}`. * `video_resolution_too_high` * The resolution of the video is too high. Please upload a video with resolution between 360x360 and 5184x2160. Current resolution is `{current_resolution}`. * `video_resolution_invalid_aspect_ratio` * The aspect ratio of the video is invalid. Please upload a video with aspect ratio between 1:1 and 2.4:1. Current resolution is `{current_resolution}`. * `video_file_broken` * Cannot read video file. Please check the video file is valid and try again. * `task_cannot_be_deleted` * (Returns raw error message) * `usage_limit_exceeded` * Not enough free credit. Please register a payment method or contact [sales@twelvelabs.io](mailto:sales@twelvelabs.io). * `video_filesize_too_large` * The video is too large. Please use a video with a size less than `{maximum_size}`. The current size is `{current_file_size}`. * `video_duration_too_short` * The video is too short. Please use a video with duration at least \{minimum\_duration} seconds. Current duration is \{current\_duration} seconds. * `video_duration_too_long` * The video is too long. Please use a video with duration at most \{maximum\_duration} seconds. Current duration is \{current\_duration} seconds. Note that the minimum and maximum durations depend on the models enabled for your index. For details, see the input requirements of each model on the [Marengo](/v1.3/docs/concepts/models/marengo) and [Pegasus](/v1.3/docs/concepts/models/pegasus#video-file-requirements) pages. If both models are enabled, the most restrictive requirements apply. # The `/connections` endpoints The following codes apply to the `/connections` endpoints. * `connection_not_found` * The specified connection does not exist. * `connection_not_active` * The connection is not active. Reconnect the account and try again. * `import_not_found` * The specified import does not exist. * `redirect_uri_invalid` * The redirect URI failed validation. It must use HTTPS, resolve to a public host, contain no wildcards, and stay within the length limit. * `redirect_uri_already_exists` * The redirect URI is already registered on your account. * `redirect_uri_not_found` * The specified redirect URI does not exist. * `redirect_uri_limit_exceeded` * Your account has reached the maximum number of registered redirect URIs. The following codes appear in the `error` object of an individual item in the import details. They are not returned as an HTTP response status. * `source_unavailable` * The file could not be accessed at the provider. It may have been moved or deleted, or its permissions may have changed. * `source_not_authorized` * The app is not authorized to access this file. Select it through the connector's file picker, then retry the import. * `unsupported_media_type` * The file is not a supported media type and cannot be imported. * `video_filesize_too_large` * The video file at the provider exceeds the maximum ingestible size of 10GB. * `audio_filesize_too_large` * The audio file at the provider exceeds the maximum ingestible size of 4GB. * `media_filesize_too_large` * The image file at the provider exceeds the maximum ingestible size of 32MB.