> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mayaresearch.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Common mistakes

> The things that actually go wrong, and what they look like.

Every one of these has been reported as something else first. The symptom rarely
points at the cause.

<AccordionGroup>
  <Accordion title="Treating the response as a WAV file" icon="file-audio">
    The body is **headerless PCM**. Writing it to `out.wav` and double-clicking
    fails or plays static. Convert it, or wrap it with a 44-byte WAV header in
    code — see [Playing the audio](/guides/streaming).
  </Accordion>

  <Accordion title="Saving the response without checking the status" icon="triangle-exclamation">
    On any error the body is **JSON, not audio**. `curl --output`, `wget -O` or
    `open(f,"wb").write(r.content)` will write that JSON into your `.pcm` file.
    Converting it yields a silent 0-second clip — so a 400 shows up as "the
    audio came back empty".

    Use `curl --fail-with-body`, or check `r.status_code` / `res.ok` before
    writing anything.
  </Accordion>

  <Accordion title="Playing at the wrong sample rate" icon="wave-square">
    It is **24000 Hz, mono, 16-bit LE**. Playing it as 44100 makes it fast and
    high-pitched; playing it as stereo makes it noise.

    Almost every "the audio sounds broken" report is one of these two.
  </Accordion>

  <Accordion title="Setting the wrong language" icon="language">
    Hindi text with `"language":"ta"` is pronounced with Tamil rules and sounds
    wrong — **no error is raised**. If unsure, or if the sentence mixes
    languages, omit the field rather than guessing.
  </Accordion>

  <Accordion title="Misspelling the voice" icon="quote-left">
    Only `Ananya` and `Arjun` exist. `"Ananaya"` returns 400 rather than
    silently substituting, so you are never billed for audio in a voice you did
    not ask for.
  </Accordion>

  <Accordion title="Buffering the whole response before playing" icon="hourglass">
    Discards the streaming advantage entirely — 120 ms becomes 730 ms. Play
    chunks as they arrive.
  </Accordion>

  <Accordion title="Opening a new connection per request" icon="plug">
    Pays the TLS handshake every time: \~300 ms, on every call.
  </Accordion>

  <Accordion title="Putting the key in browser JavaScript" icon="lock">
    Anything shipped to a browser is public. Call from your server, and proxy if
    a browser needs the audio.
  </Accordion>

  <Accordion title="Retrying a 400 or 401" icon="rotate-right">
    Deterministic — the same request fails identically forever. Only 502 and 5xx
    are worth retrying.
  </Accordion>

  <Accordion title="An unexpected 403" icon="shield">
    A `403` whose body is **not JSON** did not come from us. It is a request
    filter reacting to your HTTP client's default User-Agent. Setting any
    User-Agent clears it — see [Errors](/reference/errors).
  </Accordion>
</AccordionGroup>