Error Codes

Error codes, HTTP status codes, and troubleshooting for the HeyGen API

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.

---

Error codes

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 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.

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.

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. Use a different value or delete the existing resource first.

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.

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 or when submitted content contains inappropriate content. Create a new resource 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.

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.

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.

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.

ephemeral_upload_disabled

HTTP status: 400

Eager upload (direct-to-S3 pre-upload followed by an ephemeral commit on the create request) is temporarily disabled for your account. Fall back to the standard upload flow by supplying input_video_id or google_url instead. If the error persists, retry later or contact HeyGen support.

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.

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.