BerriAI/litellm · error · AzureSpeechAudioTranscriptionException

Azure AI Speech transcription failed with RecognitionStatus=

Error message

Azure AI Speech transcription failed with RecognitionStatus={recognition_status}.

What it means

After Azure's speech-to-text API returns, LiteLLM inspects the `RecognitionStatus` field of the JSON body. Any value other than 'Success' (e.g. 'NoMatch', 'InitialSilenceTimeout', 'BabbleTimeout', 'Error') raises this exception with the HTTP status of the raw response attached. It means the request reached Azure but recognition itself did not succeed.

Source

Thrown at litellm/llms/azure/audio_transcription/transformation.py:132

        audio_file: FileTypes,
        optional_params: dict,
        litellm_params: dict,
    ) -> AudioTranscriptionRequestData:
        processed_audio: Final = process_audio_file(audio_file)
        return AudioTranscriptionRequestData(
            data=processed_audio.file_content,
            files=None,
            content_type=processed_audio.content_type,
        )

    def transform_audio_transcription_response(
        self,
        raw_response: httpx.Response,
    ) -> TranscriptionResponse:
        response_json: Final = raw_response.json()
        recognition_status: Final = response_json.get("RecognitionStatus")
        if recognition_status is not None and recognition_status != "Success":
            raise AzureSpeechAudioTranscriptionException(
                message=(f"Azure AI Speech transcription failed with RecognitionStatus={recognition_status}."),
                status_code=raw_response.status_code,
                headers=raw_response.headers,
            )

        text: Final = self._extract_text(response_json)
        response: Final = TranscriptionResponse(text=text)
        response._hidden_params = response_json
        return response

    def get_error_class(self, error_message: str, status_code: int, headers: dict | httpx.Headers) -> BaseLLMException:
        return AzureSpeechAudioTranscriptionException(
            message=error_message,
            status_code=status_code,
            headers=headers,
        )

    def _resolve_stt_base_url(self, api_base: str) -> str:

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Inspect the full response stored in response._hidden_params / the exception body for the exact RecognitionStatus value.
2. Pre-check audio: non-empty, correct sample rate (16kHz for STT v3.1), valid WAV/OGG container, reasonable duration.
3. Match the `language` optional param to the spoken language of the audio.
4. For silence timeouts, trim leading/trailing silence or raise speech phrases thresholds before sending.
5. Treat NoMatch as a soft failure: log and skip the file rather than retrying, since retrying identical audio yields the same result.

Example fix

# before
resp = litellm.transcription(model='azure/speech', file=f, api_base=base, api_key=key)
text = resp.text

# after
from litellm.exceptions import LiteLLMException
try:
    resp = litellm.transcription(model='azure/speech', file=f, api_base=base, api_key=key, language='en-US')
    text = resp.text
except LiteLLMException as e:
    if 'RecognitionStatus=NoMatch' in str(e):
        text = ''  # no speech detected; skip clip
    else:
        raise

import wave

with wave.open(path) as w:
    assert w.getnframes() > 0, 'audio file has no frames'
    assert w.getframerate() >= 16000, 'use 16kHz+ WAV for best recognition'

from litellm.exceptions import LiteLLMException

try:
    resp = litellm.transcription(model=azure_speech_model, file=f, api_base=base, api_key=key)
except LiteLLMException as e:
    msg = str(e)
    if 'RecognitionStatus=NoMatch' in msg or 'Timeout' in msg:
        return ''  # audio-level issue: skip, do not retry identical input
    raise

When it happens

Trigger: Transcribing audio that contains no speech (NoMatch), leading or trailing silence beyond Azure's limits (InitialSilenceTimeout), noise-only audio (BabbleTimeout), or corrupt/unsupported audio containers that Azure partially accepts. Also triggered by wrong `language` parameter for the spoken content.

Common situations: Batch pipelines feeding short or silent clips; uploading 8kHz phone audio to a model expecting 16kHz WAV; specifying language='en-US' for non-English audio; microphone recordings with long silent openings.

Related errors

• api_key is required for Azure AI Speech transcription.
• api_base is required for Azure AI Speech transcription. Use
• Azure AI Speech transcription requires a Cognitive Services
• Polling response missing 'status' field
• Failed to transform Braintrust response: {str(e)}

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/cba445270f135583. Report an issue: GitHub.