Errors & Warnings

Overview

The Murf TTS API reports problems in two different ways depending on the transport:

• HTTP streaming (POST /v1/speech/stream) and Synthesize (Gen 2) (POST /v1/speech/generate) return a standard HTTP status code.
• WebSocket streaming (/v1/speech/stream-input) returns JSON error and warning frames on the open connection, and uses WebSocket close codes for connection-level failures.

How to handle errors

Every WebSocket error and warning frame carries a machine-readable code alongside the human-readable text.

• Branch on error_code and warning_code, never on the prose. The wording can change at any time; the codes are stable.
• "fatal": true means nothing further is coming for that context. Stop waiting for audio or final and clean up.
• A warning is not fatal. Something was ignored or substituted, and audio generation continues.
• trace_id is present on every frame, including audio and final, not just on errors. Quote it when you contact support.

HTTP errors

These apply to POST /v1/speech/stream and POST /v1/speech/generate.

429 from HTTP streaming

A 429 from POST /v1/speech/stream includes X-Murf-Region, X-Murf-Concurrency-Limit, X-Murf-Concurrency-Used, X-Murf-Concurrency-Remaining and Retry-After (seconds), and this body:

{
  "error_code": 429,
  "error_message": "Concurrency limit reached, please upgrade your plan or contact sales.",
  "error": "concurrency_limit_exceeded",
  "region": "ap-south-1",
  "limit": 2,
  "message": "Concurrency limit reached in region 'ap-south-1'. Retry shortly or request a higher limit."
}

Branch on error, not on the message text.

WebSocket errors

An error frame looks like this:

{
  "error": "Invalid voice_id: totally-fake. The specified voice is not supported for the selected model (FALCON). Note: Falcon2.1 and Gen2 each have their own voice catalog. Use GET /v1/speech/voices?model=falcon-2.1 to fetch the list of voices supported by this model, or browse the voice library at: https://murf.ai/api/docs/voices-styles/voice-library.",
  "error_code": "INVALID_VOICE",
  "fatal": true,
  "context_id": "turn_1",
  "trace_id": "0f8bb0ef-8dcb-4815-8b3a-1e2d3c4b5a69"
}

WebSocket warnings

Warnings mean something in your frame was ignored or substituted. Audio generation continues, so you will still receive audio.

{
  "warning": "min_buffer_size must be an integer between 0 and 1000; keeping the previous value",
  "warning_code": "INVALID_BUFFER_SIZE",
  "context_id": "turn_1"
}

Connection close codes

Recommended handling pattern

import base64, json
async def read_stream(ws):
    audio = bytearray()
    while True:
        msg = json.loads(await ws.recv())
        if msg.get("type") == "session_info":
            # Only sent when you connect with include_usage=true
            print("usage:", msg["region"], msg["concurrency"])
        elif msg.get("audio"):
            audio += base64.b64decode(msg["audio"])
        elif msg.get("timestamps"):
            # Word-level timing frames (Falcon WebSocket only, when enabled)
            pass
        elif msg.get("error"):
            # Branch on the code, never on the prose.
            print("error:", msg["error_code"], msg["error"], msg.get("trace_id"))
            if msg.get("fatal"):
                break
        elif msg.get("warning"):
            print("warning:", msg["warning_code"], msg["warning"])
        elif msg.get("final"):
            print("usage:", msg.get("concurrency"))
            break
    return bytes(audio)

Handle close code 4029 around this loop. With the websockets library, catch websockets.ConnectionClosed and check e.rcvd.code.

FAQs