> ## Documentation Index > Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.app/llms.txt > Use this file to discover all available pages before exploring further. # 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 ```json theme={null} { "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](https://app.heygen.com/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](https://docs.heygen.com/reference/rate-limits) 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](https://app.heygen.com). ### `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](https://app.heygen.com/pricing) 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. 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. ### `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](https://www.heygen.com/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](https://help.heygen.com) 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](https://help.heygen.com) 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](https://help.heygen.com). ### `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](https://help.heygen.com) 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. ### `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.