Troubleshooting

Fresh

Common Issues and Solutions

Authentication Errors

Symptom	Cause	Solution
401 Unauthorized	Missing headers	Add both X-API-ID and X-API-KEY to every request
401 Unauthorized	Wrong credentials	Re-copy credentials from Creatify dashboard
401 Unauthorized	Extra whitespace	Trim whitespace from API ID and Key values
403 Forbidden	API not enabled	Enable API access in account settings

Credit Issues

Symptom	Cause	Solution
402 Payment Required	Insufficient credits	Check balance and purchase more
Higher cost than expected	Video longer than anticipated	Pre-calculate: (duration/30) x credits_per_30s
Credits not deducted	Task still processing	Credits are deducted on task completion

Task Failures

Symptom	Cause	Solution
Status stuck on pending	High server load	Wait longer; tasks are queued
Status stuck on processing	Complex generation	Wait up to 10-15 minutes
Status failed	Various	Read failed_reason in the response
Content extraction failed	URL not scrapable	Try POST /links/with_params/ with manual data
Invalid media format	Wrong file format	Use supported formats (MP4, MP3, JPG, PNG)

URL and Link Issues

Symptom	Cause	Solution
Link returns empty media	Page blocks scrapers	Provide images manually via with_params
Link returns wrong title	Page uses JS rendering	Provide title manually via with_params
Link creation hangs	URL unreachable	Verify URL is publicly accessible

Video Quality Issues

Symptom	Cause	Solution
Low resolution output	Preview not rendered	Render the final version for full quality
Avatar lip sync off	Text too fast/complex	Simplify text or use shorter sentences
Audio distortion	Voice model mismatch	Try a different voice ID
Visual artifacts	Model limitation	Try a different avatar or use Aurora

Rate Limiting

Symptom	Cause	Solution
429 Too Many Requests	Too many API calls	Implement exponential backoff
Multiple tasks failing	Too many concurrent creates	Stagger task creation by 1-2 seconds

Output URL Issues

Symptom	Cause	Solution
Output URL returns 404	URL expired	Re-fetch the task to get a fresh URL
Output URL returns 403	Temporary CDN issue	Retry download after a short wait
Cannot play video	Incomplete download	Re-download with verified content-length

Debug Checklist

When something is not working, run through this checklist:

1. Authentication -- Can you call GET /workspace/remaining_credits/ successfully?
2. Credits -- Do you have enough credits for the operation?
3. Input validation -- Are all required parameters present and valid?
4. URL accessibility -- Are all URLs publicly accessible (not behind auth)?
5. File formats -- Are media files in supported formats?
6. Status check -- What is the exact status and failed_reason?
7. Rate limits -- Are you making too many requests?
8. Network -- Can you reach api.creatify.ai from your environment?

---

See Also

• Status Codes Reference -- All status values and HTTP codes
• Authentication SOP -- Auth setup guide
• FAQ -- Frequently asked questions