Skip to main content
HyperWhisper monitors the cloud transcription and post-processing providers that you configure. It tests the connection and the API key before and during transcription. You learn about a problem before it stops a recording.

​
How health monitoring works

When you add or change an API key, HyperWhisper waits 500 ms after you stop typing. It then sends a small HTTP request to the endpoint of the provider (for example, GET /v1/models for OpenAI). This request shows that the provider is reachable and that the provider accepts your key. HyperWhisper caches the result for 60 seconds. The cache stops the app from sending a request to the provider API for each keystroke. If a transcription starts and the cached result is old, HyperWhisper runs one more health probe before it sends your audio. The transcription pipeline waits for this probe to complete. HyperWhisper never sends your audio to a provider that fails the probe. A health probe retries with backoff (3 attempts maximum) before HyperWhisper marks it as failed. One short network error does not make a provider unhealthy. HyperWhisper does not probe a key of less than 16 characters. It marks such a key as invalid without a network request.

​
Health status states

The API Keys manager shows a colored pill next to each provider that you configure.The provider key sheet opens when you click Add or Edit. In this sheet, a status banner below the key input field gives a short explanation of the current state.

​
How HyperWhisper blocks recording when a provider is unhealthy

If the provider of your current mode shows Invalid, Unreachable, or No key, HyperWhisper disables the Record button. When you put the pointer on the button, a tooltip shows that the provider is unhealthy. You can open Settings and correct the key while the button is disabled.The Checking… state does not block recording. You can start a recording immediately. The pipeline waits for the probe to complete before it sends the audio. Thus HyperWhisper never sends your audio to a provider that fails the probe.

​
Where to find provider health

1

API Keys manager

Click the menu bar icon, then go to Model Library → API Keys. Each provider that you add shows a status pill on the right side of its row. To see the full status banner in the key sheet, click Edit next to a provider.
2

Provider key sheet

The status banner below the key input field changes while HyperWhisper tests your key. The banner shows one of these three results:
  • A green checkmark (“Everything’s good to go.”)
  • An orange triangle (“Provider rejected this key. Double-check it’s still valid.”)
  • An orange wifi icon (“Couldn’t reach the provider. Check your internet, then test again.”)

​
Test connection button (macOS)

To run a health probe immediately, click Test connection in the provider key sheet. This probe does not wait for the 500 ms debounce or the background refresh cycle. The status banner then shows the result. The button is disabled while a probe is in progress, and while the key field is empty.

​
Automatic failover (HyperWhisper Cloud only)

Each HyperWhisper Cloud tier has a fallback chain. If your chosen provider fails during a request, the cloud backend tries the next provider in the chain. HyperWhisper bills you only for the provider that completed the transcription. Failover chains: The other providers have no fallback. These providers include Azure MAI, Google Gemini 3.5 Transcribe, OpenAI, Gemini, AssemblyAI, Mistral, and Soniox. If one of these providers fails, you get an error. Try again, or change to a different provider.

​
ElevenLabs from Japan and India

ElevenLabs refuses API calls from some countries. HyperWhisper Cloud runs in more than one server region, and three of these regions are in a country that ElevenLabs refuses: Tokyo, Mumbai, and Chennai. If your mode uses ElevenLabs Scribe v2 and your request arrives at one of these three regions, the backend sends the request to a server in the United States. It does this before it does any other work. The transcription then runs on ElevenLabs as usual. The redirection adds approximately 50 ms to 80 ms. The redirection works only for a request of approximately 900 KB or less. If your audio is larger, the backend removes ElevenLabs from the failover chain instead. The transcription then runs on Deepgram, or on Groq if Deepgram also fails. The answer shows the engine that ran, and the rate of that engine applies. Bring-Your-Own-Key (BYOK) providers have no automatic failover. This applies to every provider that you select. If your BYOK provider fails, you get an error and must change the provider manually.

​
Troubleshooting

Orange “Invalid” pill or “Provider rejected this key” banner Your API key is invalid or expired. Or the account for this key does not have the necessary permissions. Go to the API Keys settings. Click Edit for the applicable provider. Paste a new key from the dashboard of the provider, then click Test connection. Orange “Unreachable” pill or “Couldn’t reach the provider” banner HyperWhisper cannot connect to the API of the provider. Make sure that your internet connection is on. Wait a moment, then try again. HyperWhisper caches the health status for 60 seconds. Thus the pill can show the old status after the provider recovers. If the error continues, the provider can have an outage. Gray “Checking…” pill The health probe is in progress. You can start a recording. The pipeline waits for the result before it sends the audio. If Checking… stays for more than a few seconds, make sure that your internet connection is on. Gray “No key” or “Untested” pill This provider has no API key, or HyperWhisper did not test the key. Add a key in the API Keys settings, then click Test connection. As an alternative, select a different provider for your mode.

​
Local API /health endpoint

The macOS app gives all provider statuses through its Local API at GET /health. This endpoint returns the cached health of each cloud provider and post-processing provider. It also returns information about the installed local models. The endpoint does not start a new probe. It reads the current cached state. For installation and authentication details, see Local API.
The /health endpoint has no authentication. Thus you can use it as a liveness probe without a bearer token. All other Local API endpoints need authentication.