API errors¶

When a request fails, the HeapStream REST API responds with a non-2xx HTTP status and a JSON body describing what went wrong. Every error carries a stable machine-readable code from the list below, so you can branch on it without parsing human-readable messages.

Error response format¶

{
  "status": 422,
  "errors": [
    {
      "code": "value_too_large",
      "detail": "Value too large.",
      "pointer": "/max_size",
      "type": "https://docs.heapstream.com/reference/api_errors/#value_too_large",
      "location": "json"
    }
  ]
}

Field	Description
`status`	The HTTP status code of the response.
`errors`	One or more error details (a single request can fail several validations at once).
`errors[].code`	Stable error code, one of the values listed under Error codes.
`errors[].detail`	Human-readable description of the problem.
`errors[].pointer`	JSON Pointer to the offending field, query parameter, or header.
`errors[].type`	Link to this page, anchored at the specific error code.
`errors[].location`	Where the error originated (`json`, `query`, `path`, or `header`).

Error codes¶

`account_suspended`¶

account suspended, negative balance, please credit account

`cant_delete_audio_track_with_clips`¶

Cannot delete: fast clips of this video kept this audio track and serve its segments. Delete the clips first.

`cant_delete_default_audio_track`¶

Default audio track cannot be deleted.

`cant_delete_default_object`¶

Default object cannot be deleted.

`cant_delete_embedded_audio_track`¶

Embedded audio track cannot be deleted.

`cant_delete_source_with_clips`¶

Cannot delete: this video has clips that reuse its segments. Delete the clips first.

`cant_modify_fastclip`¶

This operation isn't allowed on a fast clip; fast clips are fixed except for metadata.

`cant_swap_same_video`¶

A video can't be swapped with itself; pick a different video.

`date_out_of_supported_window`¶

start_dt and end_dt must fall between 2020-01-01 and 2100-01-01 UTC.

`duplicate_folder_title`¶

A folder with this title already exists here.

`duplicate_profile_title`¶

A profile with this title already exists in this project.

`duplicate_upload_part`¶

Part {part_number} is listed more than once.

Message parameters: part_number

`duration_too_small`¶

Duration of the clip is too small.

`end_date_before_start_date`¶

end_dt must be greater than or equal to start_dt.

`end_time_too_big`¶

End time is bigger than duration {end_time}.

Message parameters: end_time

`endpoint_not_exists`¶

Endpoint doesn't exist.

`folder_depth_exceeded`¶

Folders can be nested at most 5 levels deep.

`folder_limit_reached`¶

Folder limit reached (200 per project).

`folder_move_invalid`¶

A folder cannot be moved into itself or one of its subfolders.

`head_request_to_url_failed`¶

Cannot make HEAD request to url

`internal_error`¶

Internal error.

`invalid_api_key`¶

Invalid api key.

`invalid_bcp47_lang_code`¶

Language is not valid BCP 47.

`invalid_filename`¶

Filename must not contain control characters.

`invalid_image_file`¶

An image file is required.

`invalid_page_format`¶

The format of the page is invalid.

`invalid_png_file`¶

Image must be valid PNG.

`invalid_subtitle_file`¶

File must be a valid vtt or srt subtitle.

`key_id_invalid`¶

Invalid key id.

`live_provider_unavailable`¶

The live streaming provider is currently unavailable. Please try again.

`live_stream_in_preview`¶

The live stream is currently in preview — go live or stop your encoder first.

`live_stream_limit_reached`¶

Live stream limit reached for your plan.

`live_stream_not_in_preview`¶

The live stream is not in preview (connect your encoder first).

`live_stream_not_live`¶

The live stream is not currently live.

`max_date_range`¶

maximum_date_range_reached of 365 days. Please contact support if you need to increase the limit

`max_keys_reached`¶

Maximum number of keys reached.

`max_projects_reached`¶

Maximum number of projects reached.

`missing_auth_header`¶

Missing auth header.

`no_caption_track`¶

The video has no caption track to generate chapters from.

`no_such_key`¶

No such key exists.

`no_such_upload_id`¶

No such upload_id exists.

`non_empty_extension`¶

Filename must have a non-empty extension.

`not_enough_storage`¶

This needs {needed} of free storage but only {free} is available.

Message parameters: needed, free

`not_project_owner`¶

Not project owner.

`one_active_chapter`¶

Only 1 active chapter is possible.

`part_too_small`¶

Part {part_number} is under the {minimum} minimum for every part but the last.

Message parameters: part_number, minimum

`payment_past_due`¶

The account's payment is past due. Update the payment method to resume uploads and AI features.

`permission_denied`¶

Missing permission {permission}.

Message parameters: permission

`poster_already_default`¶

Poster is already the default.

`profile_in_use`¶

Cannot delete: this profile is a project default, a folder default, or attached to {attached} video(s). Detach it first.

Message parameters: attached

`profile_limit_reached`¶

Profile limit reached (100 per project).

`rate_limit_reached`¶

Rate limit reached.

`resource_not_exists`¶

Resource not found.

`schema_empty`¶

You need to set at least 1 attribute.

`start_time_too_big`¶

Start time is bigger than duration. start_time={start_time}

Message parameters: start_time

`text_track_invalid_type`¶

Text track type should not be Chapter.

`too_many_posters`¶

You have reached the maximum number of posters for this video.

`unknown_upload_part`¶

Part {part_number} of this upload doesn't exist, or its etag doesn't match.

Message parameters: part_number

`upload_quota_reached`¶

upload quota reached, please upgrade your plan or contact support

`upload_size_exceeded`¶

The upload is bigger than the declared size of {declared}.

Message parameters: declared

`upload_too_big`¶

The file is bigger than the {maximum} limit.

Message parameters: maximum

`value_too_large`¶

Value too large.

Message parameters: max_size

`video_errored`¶

Video failed to download or encode.

`video_no_audio`¶

Video has no audio streams.

`video_not_ready`¶

Video is not yet in ready state.

`videos_need_status_completed`¶

Status of the videos must be completed.

`webhook_already_exists`¶

Webhook already exists.

`webhook_limit_reached`¶

Webhook limit reached.

July 19, 2026

API errors¶

Error response format¶

Error codes¶

account_suspended¶

cant_delete_audio_track_with_clips¶

cant_delete_default_audio_track¶

cant_delete_default_object¶

cant_delete_embedded_audio_track¶

cant_delete_source_with_clips¶

cant_modify_fastclip¶

cant_swap_same_video¶

date_out_of_supported_window¶

duplicate_folder_title¶

duplicate_profile_title¶

duplicate_upload_part¶

duration_too_small¶

end_date_before_start_date¶

end_time_too_big¶

endpoint_not_exists¶

folder_depth_exceeded¶

folder_limit_reached¶

folder_move_invalid¶

head_request_to_url_failed¶

internal_error¶

invalid_api_key¶

invalid_bcp47_lang_code¶

invalid_filename¶

invalid_image_file¶

invalid_page_format¶

invalid_png_file¶

invalid_subtitle_file¶

key_id_invalid¶

live_provider_unavailable¶

live_stream_in_preview¶

live_stream_limit_reached¶

live_stream_not_in_preview¶

live_stream_not_live¶

max_date_range¶

max_keys_reached¶

max_projects_reached¶

missing_auth_header¶

no_caption_track¶

no_such_key¶

no_such_upload_id¶

non_empty_extension¶

not_enough_storage¶

not_project_owner¶

one_active_chapter¶

part_too_small¶

payment_past_due¶

permission_denied¶

poster_already_default¶

profile_in_use¶

profile_limit_reached¶

rate_limit_reached¶

resource_not_exists¶

schema_empty¶

start_time_too_big¶

text_track_invalid_type¶

too_many_posters¶

unknown_upload_part¶

upload_quota_reached¶

upload_size_exceeded¶

upload_too_big¶

value_too_large¶

video_errored¶

video_no_audio¶

video_not_ready¶

videos_need_status_completed¶

webhook_already_exists¶

webhook_limit_reached¶