# What Happens When Whisper API Keys Are Missing or Invalid in bradautomates/claude-video

> Discover what happens when Whisper API keys are missing or invalid in bradautomates/claude-video. Learn about immediate error termination and how to fix it.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-07-09

---

**When Whisper API keys are missing or invalid, the bradautomates/claude-video repository immediately terminates execution with a `SystemExit` error, displaying specific instructions for configuring valid GROQ_API_KEY or OPENAI_API_KEY credentials before any network request is attempted.**

The bradautomates/claude-video repository provides a **watch** skill that relies on Whisper transcription backends (Groq or OpenAI) to process video content. Understanding how the system handles authentication failures is critical for troubleshooting deployment issues. This guide examines the exact error handling behavior implemented in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) when API keys are absent or rejected.

## How API Keys Are Discovered

The `load_api_key()` function in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) handles credential discovery by scanning environment variables and local `.env` configuration files. When no valid key is found, the function returns `(None, None)` to indicate the absence of both a backend selection and API credentials.

The function searches for `GROQ_API_KEY` (preferred) or `OPENAI_API_KEY` in the environment, falling back to `~/.config/watch/.env` for persistent configuration storage. This discovery mechanism is tested in [`tests/test_whisper.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_whisper.py), which validates behavior for both missing keys and API error responses.

## Missing API Key Behavior

Before attempting any network operations, the `transcribe_video()` function validates the presence of API credentials. When `load_api_key()` returns falsy values for either `backend` or `api_key`, the application aborts immediately with a `SystemExit` exception.

The error message provides specific remediation steps:

```bash
$ watch video.mp4
[watch] extracting audio for Whisper (None)…
SystemExit: No Whisper API key available. Set GROQ_API_KEY (preferred) or OPENAI_API_KEY in the environment or in ~/.config/watch/.env. Run `python3 /path/to/skills/watch/scripts/setup.py` to configure.

```

This guard clause prevents unnecessary audio extraction and upload attempts when authentication is impossible.

## Invalid API Key Handling

When a key is present but rejected by the remote API, the `_post_whisper()` function handles HTTP error responses. Any **4xx** status code (excluding **429** rate-limit responses) triggers immediate termination with a `SystemExit` that includes the HTTP status and server-provided error details.

Invalid keys typically generate **401 Unauthorized** responses:

```bash
export GROQ_API_KEY=invalid-key
$ watch video.mp4
[watch] extracting audio for Whisper (groq)…
[watch] audio: 340 kB — uploading to groq Whisper…
SystemExit: Whisper request failed: <urlopen error 401 Unauthorized> — {"error":{"message":"Invalid API key"}}

```

Notably, the retry logic implemented in the module only activates for network errors, timeouts, and **429** rate-limit responses. Invalid authentication credentials never trigger retry attempts, ensuring rapid failure when credentials are misconfigured. The `MAX_429_RETRIES` constant defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) controls retry behavior for rate limits only.

## Configuring Valid Credentials

To avoid authentication errors, users can configure credentials through the provided setup script or manual environment configuration. The [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) utility interactively creates the `~/.config/watch/.env` file with proper API key storage.

Valid configuration examples:

```bash

# Environment variable method

export GROQ_API_KEY=sk-real-groq-key

# Or use the setup script

python3 skills/watch/scripts/setup.py

# Or manually edit ~/.config/watch/.env

echo "GROQ_API_KEY=sk-real-groq-key" > ~/.config/watch/.env

```

When properly configured, the transcription workflow proceeds through audio extraction, upload, and segment processing without interruption:

```bash
export GROQ_API_KEY=sk-real-groq-key
$ watch video.mp4
[watch] extracting audio for Whisper (groq)…
[watch] audio: 340 kB — uploading to groq Whisper…
[watch] transcribed 12 segments via groq

```

## Summary

- **Missing keys**: Detected by `load_api_key()` in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py), causing immediate `SystemExit` with configuration instructions before any audio processing begins.
- **Invalid keys**: Result in HTTP 401/4xx errors during `_post_whisper()` execution, triggering immediate termination with detailed error messages from the API provider.
- **No retry for auth failures**: Unlike rate-limit (429) responses, invalid credentials bypass the retry logic and fail fast to prevent wasted resources.
- **Configuration support**: The [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) script provides guided configuration for persistent credential storage in `~/.config/watch/.env`.

## Frequently Asked Questions

### What error message appears when Whisper API keys are missing?

The application displays: "No Whisper API key available. Set GROQ_API_KEY (preferred) or OPENAI_API_KEY in the environment or in ~/.config/watch/.env. Run `python3 <setup.py>` to configure." This message appears via `SystemExit` in the `transcribe_video()` function before any network requests are attempted.

### Does the application retry when an invalid API key is rejected?

No. The retry logic in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) only handles network errors, timeouts, and **429** rate-limit responses. Invalid keys generating **401** or other **4xx** errors trigger immediate termination without retry attempts, as implemented in the `_post_whisper()` error handling block.

### How do I configure Whisper API keys for the watch skill?

You can export `GROQ_API_KEY` or `OPENAI_API_KEY` as environment variables, or run `python3 skills/watch/scripts/setup.py` to create a persistent configuration file at `~/.config/watch/.env`. The `load_api_key()` function automatically detects credentials in these locations when the watch skill initializes.

### What is the difference between missing and invalid key handling?

Missing keys are caught during the initial validation phase in `transcribe_video()`, preventing any audio extraction or network activity. Invalid keys pass initial validation but fail during the `_post_whisper()` HTTP request phase, returning specific API error details (such as "Invalid API key") with the HTTP status code included in the terminal output.