Error Responses

HTTP response codes from the API are used to indicate general classes of success and error. Error responses contain more detail about the error in the response body, in the "code" and "message" properties.

`code`	`enum_name`	`message`	`detail`
40009	INVALID_CREDENTIALS	Invalid credentials provided	Invalid API key or OAuth token
400101	USER_NOT_FOUND	User not found	User associated with credentials not found
400112	UNAUTHORIZED	Unauthorized	Missing or invalid authentication
401057	INVALID_ACCESS_TOKEN	Invalid access token	Invalid OAuth2 access token
401056	ACCESS_TOKEN_EXPIRED	Access token expired	OAuth2 token has expired
400561	SPACE_NOT_FOUND	space not found	Space ID not found
400573	PERMISSION_DENIED	permission denied	Insufficient permissions
400562	FORBIDDEN	forbidden	Access forbidden
400599	TIER_NOT_SUPPORT	Please upgrade to Creator / Business plan to use this feature.	Subscription tier insufficient
400631	USER_BLOCKED	Your account has been suspended due to detected violation of our policy and terms. Please read and follow our guideline carefully when using HeyGen. If you have any question, please email [email protected] for further support.	Account suspended
40001	MISSING_PARAMS	Missing required input parameters	Required parameters missing
400175	INVALID_PARAMETER	Invalid parameter	Invalid parameter value
40012	INVALID_QUERY_PARAM	Invalid querying parameter	Invalid query parameter
40065	INVALID_VIDEO_INFOS	Invalid video infos	Invalid video input data
40039	INVALID_TEXT_INPUT	Invalid text detected	Invalid text content
400105	BLOCKED_WORDS_DETECTED	Blocked words detected	Inappropriate text content
40010	VIDEO_FORMAT_NOT_SUPPORTED	Video format not supported	Unsupported video format
40031	INVALID_VIDEO_ID	Invalid video id	Invalid video ID format
400652	VIDEO_FILE_CORRUPTED	Video file corrupted	Video file is corrupted
400621	EMPTY_VIDEO_STREAM	empty video stream	Video has no video stream
400624	EMPTY_AUDIO_STREAM	empty audio stream	Video has no audio stream
40044	INVALID_AUDIO_FORMAT	Invalid audio format	Unsupported audio format
40056	FAILED_TO_GENERATE_AUDIO	Failed to generate audio	Audio generation failed
1000022	AUDIO_DURATION_TOO_LONG	Audio duration too long	Audio exceeds maximum duration
401035	AUDIO_LENGTH_MISMATCH	Audio length mismatch	Audio length doesn't match video
401015	AUDIO_CORRUPTION_ERROR	Audio or video may be corrupted	Audio/video corruption detected
400168	INAPPROPRIATE_CONTENT	NSFW content detected	NSFW content detected
400625	CELEBRITY_CONTENT	Celebrity face detected	Celebrity face detected
402007	CHILD_SAFETY_MODERATION_FAILED	Moderation failed: Underage content detected.	Underage content detected
402008	CELEBRITY_MODERATION_FAILED	Moderation failed: Celebrity detected.	Celebrity detected
402009	INAPPROPRIATE_CONTENT_MODERATION_FAILED	Moderation failed: NSFW content detected.	NSFW content detected
401003	MODERATION_POLICY_VIOLATED	Moderation policy violated	Content policy violation
400680	UNSAFE_PROMPT	Unsafe prompt	Unsafe text prompt
400165	MOVIO_VIDEO_TOO_SHORT	Duration is too short, try another video	Video duration too short
400150	MOVIO_VIDEO_IS_TOO_LONG	Video is too long	Video duration too long
400128	MOVIO_PHOTAR_DURATION_TOO_LONG	Duration is too long	Photo avatar duration too long
400664	TRIAL_VIDEO_LIMIT_EXCEEDED	You have reached your daily trial video limit	Trial limit exceeded
400140	MOVIO_API_EXCEED_RATE_LIMIT	Exceed rate limit	Rate limit exceeded
401028	QUOTA_LIMIT	Quota limit	Quota limit reached
40019	EXCEED_USAGE_LIMIT	exceed usage limit	Usage limit exceeded
400118	CREDIT_NOT_ENOUGH	Credit not enough	Insufficient credits
400153	GUEST_GENERATE_LIMIT	Please sign up to make more videos	Guest user limit reached
400144	AVATAR_NOT_FOUND	Avatar not found	Avatar not found
400174	PHOTAR_NOT_FOUND	Photar not found	Photo avatar not found
40090	INVALID_AVATAR_INFO	Avatar info is invalid	Invalid avatar information
40004	NO_FACE_ERROR	No face detected	No face detected in image
40005	TOO_MANY_FACES_ERROR	Multiple faces found	Multiple faces detected
40006	BAD_QUALITY_IMAGE	Image quality is not good enough	Image quality insufficient
400685	AVATAR_USAGE_NOT_PERMITTED	Avatar usage not permitted	Avatar usage not allowed
400116	VOICE_NOT_FOUND	Voice not found	Voice not found
400548	TTS_VOICE_UNAVAILABLE_ERR	Text to speech voice not available	Voice not available
400552	TTS_CUSTOMER_VOICE_ERR	Voice not found	Custom voice not found
400551	TTS_PAID_VOICE_ERR	Paid voice is only available for premium users	Premium voice access required
400634	TTS_LANGUAGE_ERROR	tts language error	TTS language error
400549	TTS_PROVIDER_ERR	Text to speech provider error	TTS provider error
401030	ELEVENLABS_TTS_ERROR	tts error	ElevenLabs TTS error
400701	TTS_TOO_MANY_REQUEST_ERR	too many request, please try again later	TTS rate limit exceeded
40072	TEMPLATE_NOT_FOUND	Template not found	Template not found
400608	HEYGEN_TEMPLATE_NOT_FOUND	heygen template not found	HeyGen template not found
40092	VIDEO_GENERATE_ERROR	Video generation encounted error	Video generation failed
40071	DUPLICATE_VIDEO_GENERATION	Duplicate video generation	Duplicate generation request
400576	VIDEO_RENDER_FAILED	Failed to render video	Video rendering failed
40062	RETRIABLE_JOB_ERROR	Failed to generate video, please try again	Retriable generation error
400171	VIDEO_NOT_COMPLETED	Video not completed	Video generation not complete
404002	WORKFLOW_ALREADY_EXISTS	Workflow already exists	Workflow already exists
404003	WORKFLOW_NOT_FOUND	Workflow not found	Workflow not found
404001	WORKFLOW_VALIDATION_ERROR	Workflow input validation error	Workflow validation failed
40051	RESOURCE_NOT_FOUND	Resource is not found	Resource not found
400179	ASSET_NOT_FOUND	Asset not found	Asset not found
400114	VIDEO_NOT_FOUND	Video not found	Video not found
400578	RESOURCE_ACCESS_DENIED	resource access denied	Resource access denied
40003	UPLOAD_FAILURE	Object upload failed	File upload failed
40023	DOWNLOAD_FAILURE	Object download failed	File download failed
400609	S3_UPLOAD_FAILED	s3 upload failed	S3 upload failed
400610	S3_DOWNLOAD_FAILED	s3 download failed	S3 download failed
400616	HTTP_DOWNLOAD_FAILED	http download failed	HTTP download failed
400617	HTTP_UPLOAD_FAILED	http upload failed	HTTP upload failed
40002	IMAGE_FORMAT_NOT_SUPPORTED	Image format not supported	Unsupported image format
400543	ASSET_FORMAT_NOT_SUPPORTED	Asset format not supported	Unsupported asset format
400111	INVALID_FILE_TYPE	Invalid file type	Invalid file type
40013	QUERY_URL_FAILURE	Failed on query url	URL query failed
40045	NO_VIDEO_URL_FOUND	No video URL found	Video URL not found
401029	URL_NO_LONGER_AVAILABLE	The URL is no longer available	URL no longer available
400627	INVALID_GOOGLE_DRIVE_URL	invalid google drive url	Invalid Google Drive URL
500000	INTERNAL_SERVER_ERROR	Internal server error	Internal server error
40099	UNKNOWN_ERROR	Something is wrong, please contact [email protected]	Unknown error
400106	REQUEST_TIMEOUT	Request timeout	Request timeout
400558	API_CONNECTION_ERROR	API connection error	API connection error
400591	THIRD_PARTY_ERROR	third party error	Third party service error
40042	TRANSCODE_ERROR	Transcoding Error	Video transcoding failed
400611	VIDEO_TRANSCODE_NOT_READY	video transcode is not ready	Video transcode not ready
40032	PROCESS_VIDEO_STREAM_ERROR	Process video stream error	Video stream processing error
40033	PROCESS_VIDEO_ANALYZE_ERROR	Process video analyze error	Video analysis error
400672	SRT_FILE_ERROR	SRT file error	SRT subtitle file error
40041	JOB_NOT_READY	Job not ready	Job not ready
40043	INVALID_JOB_ID	Invalid Job ID	Invalid job ID
40029	UNKNOWN_JOB_TYPE	Unknown job type	Unknown job type
400164	MOVIO_JOB_NOT_FOUND	HeyGen job not found	Job not found
400557	MISSING_JOB_CONTEXT	Missing job context	Job context missing
40038	PAYMENT_NOT_READY	Payment not ready	Payment not ready

Additional Context-Specific Errors

Scenario	Error Message	HTTP Status	Description
Video Dimension Validation	Video width or height must be smaller than 4096 and larger than 128	400	Invalid video dimensions
Video Dimension Validation	Video width and height must be even number	400	Dimensions must be even numbers
URL Validation	not a valid URL: {url}	400	Invalid URL format provided
Video Input Validation	either url or video_asset_id needs to be provided	400	Missing video source
Asset Validation	Video asset not found: {asset_id}	404	Referenced video asset missing
Voice Validation	Voice not found: {voice_id}	400	Invalid voice ID
TTS Validation	TTS voice must be provided with text voice settings	400	Missing TTS settings
Folder Access	Resource access denied	403	No access to specified folder
Content Safety	Please upgrade your plan to generate 4K videos	400	4K requires paid plan

Streaming API

HTTP Status Code	`code`	`message`	Description
400	10001	Session state wrong: new	The session state is incorrect; it should not be "new".
400	10002	Session state wrong: connecting	The session state is incorrect; it should not be "connecting".
400	10003	Session state wrong: connected	The session state is incorrect; it should not be "connected".
400	10004	Session state wrong: closing	The session state is incorrect; it should not be "closing".
400	10005	Session state wrong: closed	The session state is incorrect; it should not be "closed".
404	10006	Session not found	The specified session could not be found.
429	10007	Concurrent limit reached	The concurrent limit for the user's plan has been reached; upgrade your plan for formal usage.
404	10012	Avatar not found	The specified avatar could not be found.
403	10013	Avatar not allowed	The specified avatar is not allowed.
429	10014	Session full	The session is full; please try again later.
429	10015	Trial API limit reached	The trial API limit has been reached.