Why Your HeyGen API Integration Fails at Scale (And How to Fix It)
By Umar Asghar, AI Integration Engineer
TL;DR
- -The avatar not found error is usually a wrong ID type (talking photo ID in the avatar field) or a stale cached ID, not a HeyGen outage.
- -Webhooks that stop firing after 50 videos trace back to ignored 429 rate-limit responses or a webhook endpoint that responds too slowly.
- -Mangled names in videos come from Unicode normalization and dirty CRM data, not HeyGen's renderer.
- -Webhooks are notifications, not truth. A reconciliation poll against /v1/video_status.get catches every dropped event.
- -Under 50 videos a day, Zapier works. Past that, you need a queue, retries, and monitoring, or failures go silent.
HeyGen API integrations fail at scale for three reasons: avatar ID mismatches between the v1 and v2 APIs, unhandled rate limits and concurrency caps that silently kill webhook delivery, and raw CRM data injected into video templates without sanitization. Each works fine in testing and breaks in production.
Why does the HeyGen avatar not found error keep appearing?
The error is misleading. Your avatar almost always exists. The request is referencing it wrong. Three causes account for nearly every case.
1. Wrong ID type. HeyGen has two character types, avatar and talking_photo, and they use different ID fields in the POST /v2/video/generate payload. Pass a talking photo ID inside an avatar_id field and the API cannot resolve it, even though the asset sits right there in your dashboard.
2. API version mismatch. Code written against the v1 API often carries avatar references the v2 endpoints do not accept. Pull the canonical list from GET /v2/avatars and use only what it returns.
3. Stale cached IDs. Teams cache the avatar list once at deploy time. Then someone deletes or re-uploads an avatar in the dashboard, and every queued job holding the old ID fails at render time, hours after the change.
// The fix: validate before enqueue, not after failure
1. On startup and every 6 hours: fetch GET /v2/avatars, cache the ID set
2. Before enqueueing any video job: check the requested ID against the cache
3. On cache miss: re-fetch once, then fail fast with a logged, alertable error
Why do HeyGen webhooks stop firing after 50 videos?
They usually never stopped. Either your side stopped receiving, or your submissions stopped succeeding. Check your 429s first - fire-and-forget code discards those responses. No video was created, so no avatar_video.success webhook will ever arrive. Check your endpoint response time second - webhook receivers must return a 2xx quickly. Return 200 immediately and process async.
// The fix pattern
1. Submit through a queue with a concurrency cap matched to your HeyGen plan
2. On 429: exponential backoff with jitter, max 5 attempts, then dead-letter
3. Webhook endpoint: ack with 200 in under 1 second, process async
4. Dedupe processing on video_id (HeyGen may deliver an event more than once)
5. Reconciliation job: poll /v1/video_status.get for any job with no webhook after 30 minutes
Why are names mis-rendered in personalized videos at volume?
Because CRM data is dirty and Unicode is hard. The “e with accent” in “Jose” can be encoded as one precomposed character (NFC) or as “e” plus a combining accent (NFD). Data exported from macOS tools often arrives as NFD, and depending on how your code escapes the payload, the render shows a stray mark. Normalize every string to NFC before it touches the API.
// Sanitization pipeline (run before every job)
1. Trim whitespace, strip emojis and control characters
2. Normalize to NFC
3. If the field is ALL CAPS or all lowercase, apply title case
4. If the first-name field exceeds ~20 characters or contains a comma, flag for review
5. Keep a test fixture of hard names and run it against every template change
When does DIY break, and when should you hire an integration engineer?
Honest answer: later than vendors want you to think, earlier than most teams notice. Under 50 videos a day, Zapier or Make plus the HeyGen API is genuinely fine. Past 50 a day, the math changes. Rate limits bite, webhook volume exposes slow endpoints, and a 2 percent silent failure rate means dozens of dropped leads a week that nobody sees.
The test: if you cannot say how many of last week’s videos failed and why, you are past the DIY line. You just have not seen the cost yet.
Fix it with a Pipeline Audit
If your team has already hit these failure modes, the Pipeline Audit maps your current integration and tells you exactly what needs to change. Free, with a written blueprint you keep whether or not we build anything.
Get your Pipeline Audit
Every build ships with the Working Pipeline Guarantee. Scoped, priced, and delivered fixed-price.
FAQ
What does the HeyGen avatar not found error mean?
The ID in your request does not match an asset the API can resolve, not that the avatar is gone. Check three things: a talking photo ID passed in the avatar_id field, a v1 ID used against v2, or a stale cached avatar list. Validate IDs against GET /v2/avatars before submitting.
Why is my HeyGen webhook not firing?
Most often the video was never created because your submission hit a 429 rate limit your code ignored. Second most often, your endpoint responds too slowly and deliveries fail. Log every submission response, ack webhooks in under a second, and poll /v1/video_status.get for jobs with no event after 30 minutes.
How many videos can I generate at once with the HeyGen API?
HeyGen caps concurrent video generation by plan tier. Requests beyond the cap return 429 responses. Match your queue's worker concurrency to your plan's limit and retry 429s with backoff instead of dropping them.
How do I retry failed HeyGen video generations?
Separate the failure types. For 429s and 5xx responses, retry with exponential backoff and jitter, capped around 5 attempts. For render failures reported via avatar_video.fail, retry once, then dead-letter the job for human review. Never retry blindly; you will burn credits on jobs that fail for a data reason.
ABOUT THE AUTHOR
Umar Asghar is the CTO of Kastiv. He builds production HeyGen and Synthesia integrations for sales teams and marketing ops teams.