Error Codes

HeyGen uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error with the information provided (e.g., a missing parameter, insufficient credits, or a resource not found). Codes in the 5xx range indicate an error on HeyGen’s servers. Every error response includes a machine-readable code, a human-readable message, and a doc_url linking to the relevant section below. Some errors that relate to a specific request field also include a param attribute.

Error response format

{
  "error": {
    "code": "insufficient_credit",
    "message": "Your account has 5 credits but this video requires 10 credits.",
    "doc_url": "https://developers.heygen.com/docs/error-codes#insufficient-credit"
  }
}

Attribute	Type	Description
`code`	string	A short, machine-readable identifier for the error. See the full list below.
`message`	string	A human-readable description of what went wrong and, where possible, how to fix it.
`param`	string	The request field that caused the error. Only present for validation errors.
`doc_url`	string	A link to the documentation for this specific error code.

HTTP status code summary

Status	Meaning
`200 OK`	Everything worked as expected.
`400 Bad Request`	The request was malformed or contained invalid parameters.
`401 Unauthorized`	No valid API key was provided.
`402 Payment Required`	The request requires additional credits or a plan upgrade.
`403 Forbidden`	The API key doesn’t have permission to perform the request.
`404 Not Found`	The requested resource doesn’t exist.
`429 Too Many Requests`	Too many requests hit the API too quickly, or a usage quota was exceeded.
`500 Internal Server Error`	Something went wrong on HeyGen’s end.

`unauthorized`

HTTP status: 401 The API key provided is invalid, expired, or missing. Verify that you are sending your API key in the X-Api-Key header and that the key is active in your HeyGen account settings.

`forbidden`

HTTP status: 403 The API key is valid but does not have permission to perform the requested action. This can occur when accessing organization-level resources with a member-level key.

`resource_access_denied`

HTTP status: 403 The authenticated user does not have access to the specific resource referenced in the request. The resource may belong to a different user or organization. Verify that the resource ID is correct and belongs to your account.

`ai_vendor_access_restricted`

HTTP status: 403 The workspace has restricted which AI vendor companies may be used. The action or model you requested relies on a vendor that is not allowed under the workspace’s AI vendor access policy. Ask a workspace administrator to update the policy if this vendor should be permitted.

`voice_not_usable`

HTTP status: 403 The voice referenced in the request cannot currently be used to generate this video. The voice is in a state that blocks generation and will not resolve on retry. Select a different voice.

`rate_limit_exceeded`

HTTP status: 429 You are sending requests too frequently. Back off and retry with exponential backoff. Check the Retry-After response header for the number of seconds to wait before retrying. See our rate limits documentation for per-endpoint limits.

`quota_exceeded`

HTTP status: 429 You have exceeded a usage quota (e.g., the free-tier limit for video agent or AI clip requests). Upgrade your plan or wait for your quota to reset. Check your current usage in the HeyGen dashboard.

`insufficient_credit`

HTTP status: 402 Your account does not have enough credits to complete this request. The error message includes how many credits you have and how many are required. Purchase additional credits or reduce the scope of your request (e.g., shorter video duration, fewer scenes).

`trial_limit_exceeded`

HTTP status: 402 You have reached the video generation limit for trial accounts. Upgrade to a paid plan to continue creating videos.

`subscription_required`

HTTP status: 402 You have used all the credits included in your pay-as-you-go trial, and further top-ups are not available on your account. Choose a plan to continue making API requests — see pricing. This is distinct from insufficient_credit: buying more credits will not resolve it, because purchases are no longer available. Subscribing to a plan is the only action that restores API access.

`plan_upgrade_required`

HTTP status: 402 The requested feature or resource requires a higher subscription tier than your current plan. This can occur when:

Using a premium avatar that is not available on your plan.
Accessing an integration that requires a higher tier.
Requesting a resolution or feature gated by plan level.

Upgrade your plan in the HeyGen dashboard to access this feature.

`video_not_found`

HTTP status: 404 No video, draft, or video translation was found matching the provided ID. Verify that:

The video_id is correct and was not mistyped.
The video has not been deleted.
The video belongs to your account.

`avatar_not_found`

HTTP status: 404 No avatar was found matching the provided ID. This applies to all avatar types — standard avatars, photo avatars (photars), instant avatars, and avatar kits. Verify that:

The avatar_id is correct.
The avatar has finished training (if recently created).
The avatar belongs to your account or is a public avatar.

`voice_not_found`

HTTP status: 404 No voice was found matching the provided ID. Verify that the voice_id is correct and that the voice is available in your account. If using a cloned voice, ensure it has finished processing.

`template_not_found`

HTTP status: 404 No template was found matching the provided ID. Verify that the template_id is correct and that the template is shared with your account or is publicly available.

`asset_not_found`

HTTP status: 404 No asset was found matching the provided ID. Assets may have been deleted or may not have finished uploading. Verify that the asset_id was returned from a successful POST /v1/asset call and that the asset has not been removed.

`webhook_not_found`

HTTP status: 404 No webhook endpoint was found matching the provided ID. Verify that the endpoint_id is correct and that the webhook has not been deleted. List your existing webhooks with GET /v3/webhooks/endpoints to find valid endpoint IDs.

`batch_not_found`

HTTP status: 404 No batch was found matching the provided ID. Verify that the batch_id is correct and that the batch belongs to your account.

`resource_not_found`

HTTP status: 404 The requested resource was not found. This is a generic not-found error for resources that do not have a more specific error code (e.g., streaming sessions, audio records). Verify that the resource ID is correct and belongs to your account.

`invalid_parameter`

HTTP status: 400 One or more request parameters are invalid, missing, or in the wrong format. The message field describes which parameter failed validation and why. The param field, when present, identifies the specific field. Common causes:

A required field is missing from the request body.
A field value is the wrong type (e.g., string instead of number).
A field value is outside the allowed range or not in the set of accepted values.
The request body is not valid JSON or is not a JSON object.

`conflict`

HTTP status: 409 The request conflicts with existing state. For example, attempting to create a webhook endpoint with a URL that is already registered for your account, or creating a brand glossary whose name another glossary in your workspace already uses (names are compared without regard to case). Use a different value or delete the existing resource first.

`stale_workflow_draft`

HTTP status: 409 The workflow draft moved before your write landed — either the expected_draft_revision you sent no longer matches, or another editor replaced the draft while a publish was compiling. Nothing was written. Re-read the workflow to pick up the current draft_revision and reapply your change; retrying the same request unchanged will keep failing.

`workflow_archived`

HTTP status: 409 The workflow definition is archived, so it cannot be published or modified. This is terminal for that definition — retrying will not help. Create a new workflow instead.

`workflow_run_admission_refused`

HTTP status: 409 The workflow run was created, but its coordinator workflow was authoritatively refused by workflow scheduling — its inputs failed scheduling validation. This is terminal for the run: retrying the same request will not help. Check the run’s status for details, or contact HeyGen support with the run id.

`resource_not_ready`

HTTP status: 409 The requested resource exists but is not yet in a ready state. This can occur when a video translation is still processing or an instant avatar has not finished training. Poll the resource status and retry once it reaches a ready state. Also returned when the uploaded object is not yet present in storage (e.g. POST /v3/assets/{asset_id}/complete called before the upload PUT landed); safe to retry.

`artifact_unavailable`

HTTP status: 409 The requested artifact exists but permanently failed to resolve to a durable storage location, so no download URL can be issued. Unlike resource_not_ready, this is terminal — retrying or polling will not change the outcome. Inspect the artifact’s failure field for the reason.

`request_in_progress`

HTTP status: 409 A prior request with this Idempotency-Key is still in progress. Wait for the original request to complete and retry. Once the original request finishes, subsequent retries with the same key within 24 hours replay the original response.

`content_policy_violation`

HTTP status: 400 The request was rejected for violating HeyGen’s content policy. This can occur when an instant avatar does not pass the moderation review, when submitted content contains inappropriate content, or when an uploaded image/video asset that was flagged by moderation is used in a request. Create a new resource (or upload a new asset) that complies with our usage policy.

`unlimited_mode_disabled`

HTTP status: 400 The avatar does not support unlimited mode. Use a different avatar, or use Avatar IV or Avatar V.

`avatar_consent_required`

HTTP status: 400 The avatar group used in the request requires consent before it can be used to generate a video (its instant-avatar consent was skipped, rejected, or never completed). Complete the consent flow for the avatar group (e.g. POST /v3/avatars/{group_id}/consent), then retry the request.

`resource_limit_reached`

HTTP status: 400 You have reached the maximum number of a resource allowed for your account (e.g., voice clone slots, instant avatar redo attempts, verified avatar group slots). Delete unused resources to free up capacity, wait for limits to reset, or contact HeyGen support to request a higher limit.

`voice_unavailable`

HTTP status: 400 The requested voice exists but is not in a usable state. This occurs when a cloned voice failed processing, expired, or was canceled. Delete the voice and create a new voice clone, or use a different voice.

`script_too_short`

HTTP status: 400 The script provided is too short to generate a video. HeyGen requires the text-to-speech audio to be at least 1.0 second long. Very short scripts (a single word, a period, or a few characters) will not produce enough audio. Add more content to your script and retry the request.

`tts_text_invalid`

HTTP status: 400 The text provided for text-to-speech conversion is invalid or cannot produce speech. Check that the script is not empty and contains speakable words or valid pauses, then retry.

`video_too_long`

HTTP status: 400 The input video exceeds the maximum supported duration for this endpoint (for example, filler word removal supports sources up to 2 hours). The error message includes the probed duration and the limit. Trim or split the video and retry.

`no_audio_track`

HTTP status: 400 The input video has no audio track. Speech-based processing (such as filler word removal) needs speech audio to transcribe. Provide a video that contains an audio stream.

`download_failed`

HTTP status: 400 A URL provided in your request could not be downloaded. This applies to video URLs, image URLs, audio URLs, and any other user-supplied resource link. Common causes:

The URL is not publicly accessible (authentication required, private video, restricted sharing settings).
The URL is malformed or points to a page rather than a direct file.
The remote server refused the connection or returned an error.
For Google Drive links, the file must be shared with “Anyone with the link” access.
For YouTube/Vimeo, the video must be public (unlisted or private videos are not supported).

Check the message field for details about which URL failed and why.

`batch_too_large`

HTTP status: 400 The batch request contains more items than the maximum allowed. Split the request into smaller batches and retry.

`batch_item_invalid`

HTTP status: 400 One or more items in the batch request failed validation. Check the message field for details about which item failed and why, correct the payload, and retry.

`too_many_ids`

HTTP status: 400 The request specified more IDs than the maximum allowed in a single call. Reduce the number of IDs and split the request across multiple calls.

`video_delete_failed`

HTTP status: 500 The video could not be deleted due to an internal error. Retry the request. If the error persists, contact HeyGen support with the video_id.

`internal_error`

HTTP status: 500 An unexpected error occurred on HeyGen’s servers. This is not caused by your request. If the error persists, contact HeyGen support and include the full error response for faster debugging.

`voice_provider_error`

HTTP status: 502 An upstream voice provider that HeyGen relies on (for text-to-speech, voice cloning, or voice design) returned an error or was temporarily unavailable. This is not caused by your request. Retry after a short delay. If the error persists, contact HeyGen support and include the full error response for faster debugging.

`not_implemented`

HTTP status: 501 The requested endpoint exists, but its server-side implementation has not shipped yet. Retrying the same request will not succeed until the feature is implemented.

`gateway_timeout`

HTTP status: 504 A resource referenced in your request (e.g., a URL for background audio or an image) could not be downloaded within the time limit. Verify that the URL is publicly accessible, responds quickly, and is not blocked by firewall or geo-restrictions. Retry if the target server was temporarily slow.

`service_unavailable`

HTTP status: 503 A downstream service needed to fulfill your request (for example, the text-to-speech synthesis backend or video quality comparison judge) is temporarily overloaded or unavailable. This is transient and not caused by your request. Back off and retry after a short delay. Also returned when publishing a workflow version loses the version-number allocation race repeatedly, which means several publishes are contending on the same workflow. Same guidance: back off and retry. Also returned when starting a workflow run could not confirm its coordinator workflow was accepted (a timeout, transport error, or an unrecognized response from workflow scheduling). This is safe and expected to retry: repeat the request with the same Idempotency-Key to resume the same run.

`hyperframes_project_invalid`

HTTP status: 400 The HyperFrames project zip you supplied isn’t a valid composition. Make sure the zip contains an index.html (or the composition entry file you specified) at the root or in a single top-level directory, and that it opens correctly with the hyperframes CLI before submitting.

`hyperframes_project_too_large`

HTTP status: 413 The HyperFrames project zip exceeds the maximum allowed size for the ingestion method you used. Use asset_id (pre-upload via POST /v1/asset) for projects larger than the url / base64 caps.

`hyperframes_render_not_found`

HTTP status: 404 No HyperFrames render with that render_id exists for your space, or the render has been soft-deleted. Check that the render_id is correct and was created under the same API key / space.

`hyperframes_render_failed`

HTTP status: 500 The HyperFrames render failed server-side while producing the video. The project was accepted and the render started, so this is not a problem with your request payload. Retry the render; if it fails repeatedly for the same project, verify the composition renders locally with the hyperframes CLI before contacting support with the render_id.

​Error response format

​HTTP status code summary

​Error codes

​unauthorized

​forbidden

​resource_access_denied

​ai_vendor_access_restricted

​voice_not_usable

​rate_limit_exceeded

​quota_exceeded

​insufficient_credit

​trial_limit_exceeded

​subscription_required

​plan_upgrade_required

​video_not_found

​avatar_not_found

​voice_not_found

​template_not_found

​asset_not_found

​webhook_not_found

​batch_not_found

​resource_not_found

​invalid_parameter

​conflict

​stale_workflow_draft

​workflow_archived

​workflow_run_admission_refused

​resource_not_ready

​artifact_unavailable

​request_in_progress

​content_policy_violation

​unlimited_mode_disabled

​avatar_consent_required

​resource_limit_reached

​voice_unavailable

​script_too_short

​tts_text_invalid

​video_too_long

​no_audio_track

​download_failed

​batch_too_large

​batch_item_invalid

​too_many_ids

​video_delete_failed

​internal_error

​voice_provider_error

​not_implemented

​gateway_timeout

​service_unavailable

​hyperframes_project_invalid

​hyperframes_project_too_large

​hyperframes_render_not_found

​hyperframes_render_failed