# What Does ReClip Do When a Video Is Unavailable? Error Handling Explained

> Discover how ReClip handles unavailable videos by returning JSON error responses and displaying visual error cards. Learn about its robust error handling for metadata and downloads.

- Repository: [Avery Gan/reclip](https://github.com/averygan/reclip)
- Tags: how-to-guide
- Published: 2026-09-03

---

**ReClip returns structured JSON error responses and displays visual error cards in the UI when a requested video is unavailable, handling failures at both the metadata fetching and download stages without crashing the application.**

ReClip is an open-source video downloading application that gracefully handles unavailable videos through robust error detection and user feedback mechanisms. When `yt-dlp` encounters a removed, geo-blocked, or otherwise inaccessible video, ReClip captures the failure and communicates it clearly to the user through its Flask backend and dynamic frontend interface.

## How ReClip Detects Unavailable Videos

ReClip monitors for unavailable videos at two critical points in its processing pipeline. Understanding both stages helps explain why the application remains stable even when video URLs fail.

### Metadata Fetching Stage (`/api/info` Endpoint)

When a user submits a video URL, ReClip first attempts to fetch metadata through its `/api/info` endpoint. This endpoint executes `yt-dlp` with the `-j` flag to retrieve JSON-formatted video information.

According to the [reclip source code](https://github.com/averygan/reclip/blob/main/app.py), the relevant implementation in [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) (lines 106-108) works as follows:

```python
result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
if result.returncode != 0:
    # yt‑dlp reports an error → propagate as JSON error

    return jsonify({"error": result.stderr.strip().split("\n")[-1]}), 400

```

If `yt-dlp` exits with a non-zero status code—indicating the video was removed, geo-restricted, or the URL was invalid—ReClip immediately returns an HTTP 400 response containing the last line of `stderr` as the error message. The frontend JavaScript receives this response and renders an **error card** that explains why the video could not be loaded.

### Download Stage (`/api/download` Endpoint)

Even if metadata retrieval succeeds, a video may become unavailable during the actual download. ReClip handles this scenario through its background worker architecture.

The `/api/download` endpoint spawns a thread that executes `yt-dlp` with a 300-second timeout. As shown in [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) (lines 49-52):

```python
result = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
if result.returncode != 0:
    job["status"] = "error"
    job["error"] = result.stderr.strip().split("\n")[-1]   # error message shown in UI

    return

```

When the download fails, the worker:
1. Sets the job's `status` field to `"error"`
2. Stores the last line of `stderr` as the `error` message
3. Terminates the background task cleanly

Clients polling `/api/status/<job_id>` receive this updated status, triggering the UI to display a red-styled error card with an error icon and the specific failure reason.

## Error Communication Flow in ReClip

ReClip implements a **three-layer error reporting system**:

- **Backend layer**: [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) captures `yt-dlp` exit codes and stderr output
- **API layer**: Flask endpoints return structured JSON responses (400 for immediate failures, status polling for async failures)
- **Presentation layer**: [`templates/index.html`](https://github.com/averygan/reclip/blob/main/templates/index.html) renders visual error states based on response data

This architecture ensures no unhandled exceptions propagate to users. Instead, every failure path produces actionable feedback.

## Key Files Handling Unavailable Videos

| File | Purpose |
|------|---------|
| [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) | Core Flask backend containing `/api/info`, `/api/download`, and `/api/status/<job_id>` endpoints that implement unavailable-video error capture |
| [`templates/index.html`](https://github.com/averygan/reclip/blob/main/templates/index.html) | Frontend template rendering dynamic error cards from API responses |
| [`README.md`](https://github.com/averygan/reclip/blob/main/README.md) | Project documentation referencing user-visible error handling |

## Summary

- ReClip detects unavailable videos at **two stages**: metadata fetching (`/api/info`) and downloading (`/api/download`)
- **Non-zero exit codes** from `yt-dlp` trigger structured error responses rather than application crashes
- Error messages are extracted from the **last line of `stderr`** for maximum relevance
- The UI displays **visual error cards** with red styling and descriptive messages
- Background job architecture ensures **async failures** are tracked and reported through status polling

## Frequently Asked Questions

### What HTTP status code does ReClip return for unavailable videos?

ReClip returns **HTTP 400** from the `/api/info` endpoint when `yt-dlp` cannot fetch video metadata. For download failures, the job status is set to `"error"` and returned through the `/api/status/<job_id>` polling endpoint without a specific HTTP error code.

### Does ReClip crash if a video is deleted during download?

No. The background worker in `/api/download` catches all `yt-dlp` failures through exit code checking. The job state transitions to `"error"` and stores the failure reason, allowing the UI to display appropriate feedback without interrupting the application.

### Where are ReClip's error messages displayed to users?

Error messages appear in **cards rendered by [`templates/index.html`](https://github.com/averygan/reclip/blob/main/templates/index.html)**. Metadata failures show immediately upon `/api/info` response. Download failures update the corresponding job card through status polling, applying red styling and error icons to indicate failure state.

### Can ReClip distinguish between different types of video unavailability?

ReClip surfaces the raw `yt-dlp` error message from `stderr`, which typically indicates whether a video was removed, geo-blocked, age-restricted, or private. The application does not categorize these programmatically but displays the descriptive message directly to users.