Errors

Error responses across all Vyla API endpoints

All Vyla API endpoints return JSON error responses with a consistent structure. HTTP status codes are used where appropriate.

Standard Error Shape

{
  "success": false,
  "error": "<description>"
}

The /api/proxy endpoint uses a slightly different shape — it omits success and returns just { "error": "<description>" }.

---

Error Reference by Endpoint

/api/movie and /api/tv

Status	Error	Cause
400	Missing id	The id query parameter was not provided
200	success: false, results_found: 0	Scraping succeeded but no sources were found for the given ID

A 200 with success: false means scraping worked but the TMDB ID returned nothing — not a network failure. Try again or check the ID.

/api/scrape

Status	Error	Cause
400	Missing id	The id query parameter was not provided
400	Invalid or missing provider	The provider parameter was omitted or not a valid provider key
200	success: false, sources: []	The specified provider returned no results for the given ID

Valid provider values: moviedownloader, vixsrc, vidsrc, uembed, vidrock, rgshows, vidzee, embed02

/api/stream/* and /api/download/*

Status	Error	Cause
400	Missing id	The id query parameter was not provided
200	success: false, results_found: 0	All provider sub-requests completed but none returned sources

/api/download (single URL)

Status	Error	Cause
400	Missing url param	The url query parameter was not provided
400	Invalid URL	The provided URL could not be parsed
502	All fetch attempts failed	All retry attempts to reach the upstream URL failed
Upstream	Upstream returned <status>	The CDN returned a non-OK response after all retries

Special case — HLS URLs: When the URL contains .m3u8 or /playlist/, a 200 is returned with an ffmpeg_command instead of streaming the file:

{
  "success": true,
  "ffmpeg_command": "ffmpeg -headers \"...\" -i \"...\" -c copy -bsf:a aac_adtstoasc output.mp4",
  "url": "https://...",
  "referer": "https://..."
}

/api/proxy

Status	Error	Cause
400	Missing url parameter	The url query parameter was not provided
400	Invalid url	The URL could not be parsed
403	Blocked host	The target hostname is a private IP or blocked domain (SSRF protection)
502	Fetch failed: <reason>	The upstream request threw an exception
Upstream	Upstream error <status>	The proxied server returned a non-OK response

/api/player

The player returns HTML error pages rather than JSON:

Status	Body	Cause
400	<h2>Missing ?id=</h2>	The id query parameter was not provided
404	<h2>No sources found.</h2>	Scraping succeeded but no sources were found for the given ID

---

Debugging Tips

Always check `success` before using `sources`

A 200 response can still have success: false with zero results if no providers returned anything for that TMDB ID.

Zero sources? Retry.

Some providers are intermittently unavailable. A simple retry often succeeds without any code changes.

Getting 403 from a CDN stream?

This almost always means the Referer and Origin headers weren’t forwarded. Use /api/proxy with the headers param encoded as base64 JSON, or use the pre-built vlc_url from /api/stream/movie or /api/stream/tv — headers are already encoded in it.