Skip to main content
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"
  }
}
AttributeTypeDescription
codestringA short, machine-readable identifier for the error. See the full list below.
messagestringA human-readable description of what went wrong and, where possible, how to fix it.
paramstringThe request field that caused the error. Only present for validation errors.
doc_urlstringA link to the documentation for this specific error code.

​
HTTP status code summary

StatusMeaning
200 OKEverything worked as expected.
400 Bad RequestThe request was malformed or contained invalid parameters.
401 UnauthorizedNo valid API key was provided.
402 Payment RequiredThe request requires additional credits or a plan upgrade.
403 ForbiddenThe API key doesn’t have permission to perform the request.
404 Not FoundThe requested resource doesn’t exist.
429 Too Many RequestsToo many requests hit the API too quickly, or a usage quota was exceeded.
500 Internal Server ErrorSomething 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.

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

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

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