Error Handling and Troubleshooting
Understand common errors in FetchMedia API calls, including error codes for video fetching failures, processing issues, and how to resolve them effectively.
{
"error": {
"code": "INVALID_URL",
"message": "The provided URL is not supported or malformed."
}
}
{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key. Verify your `X-API-Key` header."
}
}
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests. Retry after {retry_after} seconds."
}
}
{
"error": {
"code": "PROCESSING_FAILED",
"message": "Internal server error during FFmpeg processing."
}
}
HTTP Status Codes and Error Responses
FetchMedia returns standard HTTP status codes along with JSON error bodies. Review the code and message fields in responses to diagnose issues.
Always check the error.code first—it maps directly to specific resolutions.
Use these examples to interpret common responses:
Common Video Fetch Failures by Platform
Platform-specific issues arise from privacy settings, rate limits, or content restrictions. Use the steps below for each.
TikTok videos fail due to private accounts or region blocks.
Verify Public Status
Ensure the video is public. Test the URL in an incognito browser.
Check Region
Use a VPN if geo-restricted. Retry the API call.
Retry with Delay
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.example.com/v1/fetch?url=https://www.tiktok.com/@user/video/123"
Reels often fail from login walls.
Direct Link
Use the direct Reel URL, not profile links.
Avoid Stories
Stories expire quickly—fetch Reels or IGTV instead.
Age-restricted or live videos cause issues.
Append ?bpctr=99999999 to bypass some restrictions temporarily.
Resolving FFmpeg Processing Errors
FFmpeg errors occur from incompatible formats or large files. Common codes include FORMAT_NOT_SUPPORTED and TIMEOUT.
Format Issues
Convert inputs to MP4/H.264 before processing.
Size Limits
Videos over 500MB fail—compress first.
Duration
Limit to <60s clips to avoid timeouts.
Follow these steps to debug:
Validate Input
Test without processing: Set process=false in the body.
Check Logs
Enable debug=true for detailed FFmpeg output.
Reduce Complexity
Simplify params: Use basic trims instead of effects.
Example request with error handling:
const response = await fetch('https://api.example.com/v1/process', {
method: 'POST',
headers: {
'X-API-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
url: 'https://example.com/video.mp4',
debug: true
})
});
if (!response.ok) {
const error = await response.json();
console.error(`Error ${error.error.code}: ${error.error.message}`);
}
curl -X POST \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/video.mp4",
"debug": true
}' \
https://api.example.com/v1/process
Integration Issues with n8n and Make
Tools like n8n and Make often hit auth or payload errors.
- Set HTTP node headers:
X-API-Key: {{ $env.YOUR_API_KEY }} - Parse JSON responses in a Code node.
- Use Wait node for rate limits.
Store API keys in environment variables—never hardcode.
For persistent issues, check Quickstart for base setup or contact support with full error payloads.
Last updated today