# 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 [contact@heygen.com](mailto:contact@heygen.com) 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 [contact@heygen.com](mailto:contact@heygen.com) | 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. |