Troubleshooting the API

Diagnose Rime API failures by what you observe, including failures that arrive wrapped by LiveKit, Pipecat, Vapi, or the CLI.

Many Rime API failures are silent: a request returns 200 and plausible output while doing something other than what you asked. This page starts from what you observe. For the exhaustive list of statuses and messages, see the error reference.

Capture evidence before you retry. No response carries a request ID you can quote, so record the UTC timestamp, the endpoint and region, modelId, speaker, and lang as sent, the status and full body or the WebSocket close code and its complete reason string, and whether any audio had arrived. A reproduction is often the only diagnostic available.

No audio at all

The file exists but will not play

Check what is actually in it before anything else:

file output.wav       # expect: RIFF (little-endian) data, WAVE audio
head -c 4 output.wav  # expect: RIFF

What the first bytes tell you:

• RIFF: the file has a WAV header. If it still won’t play, check its size: a file of a few hundred bytes means the stream ended early.
• {: you received JSON instead of audio. Coda and Mist v3 return JSON only for errors, so check the status code. The legacy Mist models can also return audio inside a JSON envelope.
• Unreadable binary without RIFF: on Coda and Mist v3, a missing or wildcard Accept returns raw 16-bit PCM (audio/pcm), which players won’t open. Set Accept: audio/wav.
• Readable English: a client that didn’t check the status wrote an error message to the file. An Accept naming an unsupported type, for example, returns 406 with a plain-text list of supported types.

See the quickstart’s success check.

The file is zero bytes

The request never completed. Confirm the URL is https://users.rime.ai/v1/rime-tts and reachable, and that your client is not silently following a redirect or failing TLS.

An unexpected 401

Four different messages produce a 401, and they mean different things. invalid subscription is a billing state, not a bad key, so regenerating the credential will not help. empty apikey almost always means a shell variable did not expand. See 401 in the error reference.

Audio arrives but is wrong

The voice is not the one you asked for

Most likely the speaker, modelId, and lang combination is not one the catalog serves, and it was not rejected. Verify against the Coda or Mist v3 catalog. Remember that every Coda voice serves exactly one language, so the voice determines lang.

Second possibility: modelId contains a typo. An unrecognized value is served by Mist v3 without an error, so codaa returns working audio from the wrong model.

Speed changes stop taking effect past a point

timeScaleFactor is clamped to 0.4 to 2.5 without notice. Also check the direction: timeScaleFactor below 1.0 is faster, while speedAlpha above 1.0 is faster. See Speed.

Pronunciation overrides do nothing

phonemizeBetweenBrackets works on English Mist v3 only. On Coda and non-English Mist v3 it is accepted and ignored. See the model reference.

Streaming and WebSocket problems

Timestamps never arrive

They are emitted only for English and Spanish, or when lang is omitted. In other Coda languages the stream sends chunk and done with no timestamps event and no error, so never block playback waiting for one.

The connection closes mid-utterance

A server-side failure closes with 1011 and puts the message in the close reason, often prefixed with an HTTP-equivalent status as in 400: text is too long. Log the whole reason string. Read the prefix when diagnosing, but do not branch on it.

The upgrade fails before a socket opens

Connection-time failures arrive as an HTTP status on the upgrade, not as a close code. A 429 there means the account already has as many connections open as Rime allows. Close idle connections and reuse open ones rather than opening one per utterance.

Audio is choppy or late under load

Check you are calling the nearest regional endpoint before investigating anything else, then see Latency.

Retrying safely

Retry only what can succeed on a second attempt, and know what a retry costs.

What happened	Retry?	Notes
400	No	The request is malformed. It will fail identically.
401, 403	No	Fix the credential or the account. Repeated attempts with a bad key are indistinguishable from an attack.
429 at the upgrade	Yes, after backoff	Retry the connection, not the synthesis. Reduce connection churn.
500, 502	Yes, with backoff	The only failures where an immediate retry is reasonable.
1011 close, no audio yet	Usually	Read the reason string first. If it describes a malformed request, fix the request instead of retrying.
1011 close, audio already sent	Only deliberately	See the billing warning below.
Upgrade succeeded, then silence	Reconnect	Do not retry the whole utterance without deciding what to do about the partial audio.

Retries are billed as new synthesis. Rime bills by characters synthesized, and each request is billed independently. If a connection drops partway through a long utterance, resynthesizing the full text incurs its full character count again. For long utterances, synthesize in sentence-aligned chunks and resume from the last chunk you received, so a retry only re-sends what was lost.

Rime does not send a Retry-After header, so choose your own backoff. Exponential with jitter, capped, is the usual choice.

Failures that arrive wrapped

Most developers meet the Rime API through an integration rather than directly, and see a framework exception instead of a status code. Map it back before diagnosing.

Where you are	What you see	How to get the real cause
LiveKit agents	A plugin exception during TTS, often without the HTTP status	Reproduce the same speaker, modelId, and lang with a raw cURL request. Older LiveKit Rime plugin releases default to the retired arcana identifier, so set model="coda" explicitly. See LiveKit.
Pipecat	A service error in the pipeline log	Pipecat defaults to Coda from v1.3.0. Confirm your version, then reproduce with cURL. See Pipecat.
Vapi	A provider error in the call log	Voice and model are set in the Vapi dashboard rather than in your code, so check there first. See Vapi.
Rime CLI	A command error	Run with the same values through rime curl to see the unwrapped response, and see CLI troubleshooting.
MCP server	A tool error in your assistant	list_voices needs no key, so if that works and synthesis does not, the problem is the key rather than the connection. See MCP.

The general method is the same in every row: reduce to one raw HTTP request with the identical speaker, modelId, lang, and Accept, and read the plain-text body. If the raw request succeeds, the problem is in the integration or its configuration rather than in the API.

Still stuck

Check the Rime status page first. An incident in progress explains failures that no change on your side will fix.

Contact [e-mail] with the evidence listed at the top of this page. Because no request ID exists, the reproduction and the exact timestamp are what make a report actionable.

Related

• Error reference: every status and message, per transport.
• Voices: verify a voice, model, and language combination.