Skip to main content

​
Common Issues

​
Insufficient Credits (402 Error)

Problem: You don’t have enough credits to process the video. Solution: Check your credit balance and top up if needed. 
# Check credit balance
curl -X GET https://api.videobgremover.com/v1/credits \
  -H "X-Api-Key: $API_KEY"

# Response shows remaining credits
{
  "total_credits": 100,
  "remaining_credits": 5,
  "used_credits": 95
}

​
Invalid API Key (401 Error)

Problem: Your API key is invalid or missing. Solutions:
  1. Check your API key format: vbr_ followed by 32 characters
  2. Verify the key exists in your API Management dashboard
  3. Ensure you’re using the correct header: X-Api-Key
# Correct format
curl -H "X-Api-Key: vbr_your_32_character_key_here" ...

# ❌ Wrong header name
curl -H "Authorization: Bearer vbr_..." ...

# ❌ Wrong key format  
curl -H "X-Api-Key: invalid_key" ...

​
File Too Large (413 Error)

Problem: Your video file exceeds the 1GB limit. Solutions:
  1. Compress your video before uploading
  2. Use a shorter video clip
  3. Reduce video resolution or quality

​
Job Not Found (404 Error)

Problem: The job ID doesn’t exist or doesn’t belong to your account. Solutions:
  1. Verify the job ID is correct
  2. Check that you’re using the same API key that created the job
  3. Jobs expire after 24 hours - create a new one if needed

​
Processing Failed

Problem: The job status shows “failed” with an error message. Common causes and solutions: For specific error messages, check the API response and ensure your video meets the format requirements.

​
WebM Transparency Not Working

Problem: WebM video appears opaque instead of transparent Solution: Use the correct decoder 
# ❌ Wrong - strips alpha channels
ffmpeg -i video.webm ...

# ✅ Correct - preserves alpha channels
ffmpeg -c:v libvpx-vp9 -i video.webm ...

​
SDK-Specific Issues

​
Import Errors

// ❌ Wrong import
import VideoBGRemover from '@videobgremover/sdk'

// ✅ Correct import
import { VideoBGRemoverClient, Video } from '@videobgremover/sdk'

​
FFmpeg Not Found

Problem: SDK can’t find FFmpeg for composition operations. Solutions:
  1. Install FFmpeg: brew install ffmpeg (macOS) or apt install ffmpeg (Ubuntu)
  2. Ensure FFmpeg is in your PATH
  3. Test with: ffmpeg -version
Error you’ll see: When FFmpeg is not available, you’ll get an error like: 
Error: FFmpeg not found. Please install FFmpeg: Command 'ffmpeg' not found

# Test if FFmpeg is available
ffmpeg -version

# Should output version information
# If you get "command not found", FFmpeg is not installed

​
Performance Issues

​
Slow Processing

Causes:
  • Large video files (>100MB)
  • High resolution videos (4K+)
  • Long videos (>5 minutes)
Solutions:
  1. Pre-process videos: Reduce resolution to 1080p
  2. Split long videos: Process in segments
  3. Optimize format: Use MP4 with H.264 encoding

​
Getting Help

If you’re still having issues:

📧 Email Support

Contact paul@videobgremover.com for technical support

🐛 Report Issues

Report bugs on GitHub Issues