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"
    }
  ]
}

Error codes¶

account_suspended¶

account suspended, negative balance, please credit account

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.

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_date_is_bigger_than_today¶

Not a valid date.

end_percent_not_after_start_percent¶

end_percent must be greater than start_percent.

end_time_too_big¶

End time is bigger than duration {end_time}.

Message parameters: end_time

endpoint_not_exists¶

Endpoint doesn't exist.

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.

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.

poster_already_default¶

Poster is already the default.

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

stop_seconds_out_of_range¶

stop_seconds must be 0 (play whole segments) or between 0.5 and 10.

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.

upload_quota_reached¶

upload quota reached, please upgrade your plan or contact support

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.