Skip to main content
Most Rime failures return the reason as a plain-text body: the status code carries the class of failure and the body carries the message. Two exceptions return JSON with an error field: an unhandled 500 from POST /v1/rime-tts, and /phonemize failures after authentication. Branch on the status code and Content-Type, not the body shape. Neither form has a machine-readable error code field.
No response carries a request ID. There is nothing in a response or close frame that you can quote back to support, so an accurate UTC timestamp is the single most useful thing to capture when something fails. Record everything under what to send to support at the moment it happens.

​
How failures reach you, per transport

Log the complete close reason string, because it’s the only place the message appears. The leading status is a diagnostic aid, not a stable format, so read it but don’t branch on it. Handle both failure paths: the same bad request can be rejected on the upgrade with an HTTP status, or accepted and then closed with 1011 once the socket is open.

​
400, the request was rejected

Do not rely on this error to catch a bad pairing. It is not returned for every model or transport, so an unsupported combination of speaker, modelId, and lang can be accepted and synthesized rather than rejected. Verify the combination against the Coda or Mist v3 catalog before you ship it, and treat a successful response as no evidence that the pairing was valid.
/textnorm reports text problems with its own messages: text must be a string, text must not be empty, and text exceeds max length of 10000 characters.

​
401, authentication failed

invalid subscription arrives as a 401 rather than a 402 or 403, so a billing problem can look like an authentication problem. If your key is correct and unchanged, check the account’s subscription and balance before regenerating credentials. Create and manage keys on the API Tokens page; see Authentication.

​
403, authenticated but not allowed

access forbidden means the credential is valid but the account may not use this endpoint or resource. Retrying won’t help. Contact support@rime.ai if you expect access.

​
406, the requested media type cannot be produced

modelId "<model>" can only be returned as streamed audio; set Accept to one of: ... means Accept named a concrete type the API cannot produce for that model. Coda and Mist v3 return audio only. Set Accept to one of the listed types. Retrying won’t help.

​
429, too many requests

Currently at websocket limit is returned at the WebSocket upgrade when the account already has as many WebSocket connections open as Rime allows. The limit is on connections open at the same time, not on how fast you open them. An HTTP request can also return 429 when a key sends requests faster than its rate limit. Rime doesn’t publish a connection limit, so don’t design to a specific number. Treat a 429 as a signal to back off: stop opening new connections, retry the upgrade after a delay, and reuse existing connections rather than opening one per utterance. Limits apply to the account as a whole, so on a team account, connections opened by one member count against the others.
Synthesis concurrency is separate from this connection limit, and Rime does not publish a figure for it. If you need a concurrency commitment for capacity planning, contact support@rime.ai rather than inferring one from what you observe.

​
500 and 502, the request failed on Rime’s side

These are the only failures where a retry is reasonable on its own. Retry with backoff, and see the retry guidance below before retrying anything that may already have produced audio. If 500s, 502s, or timeouts persist across retries, check the Rime status page for an incident in progress before you change your integration.

​
Retrying safely

Retry a 500 or 502. Do not retry a 400, 401, or 403: the request will fail identically and, for 401, repeated attempts with a bad credential are indistinguishable from an attack. For a 429, back off and retry the connection rather than the synthesis.
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.

​
What to send to support

Support has no request ID to look up, so include all of the following when you report a failure. Redact your API key.
  • The UTC timestamp of the failure, to the second. This matters most, because it is how support locates the request
  • The endpoint and regional endpoint you called
  • modelId, speaker, and lang exactly as sent
  • The HTTP status and the full plain-text body, or the WebSocket close code and its complete reason string
  • A minimal request that reproduces it, with the key removed
  • Whether any audio had already arrived when the failure occurred
  • API authentication: creating keys and the header format, for diagnosing 401s.
  • Voices: the catalog to verify a speaker, modelId, and lang combination against.
  • Streaming formats: valid audioFormat values and their tradeoffs.
  • WebSockets: which endpoint reports structured errors and which does not.