Skip to main content
Rime returns the failure reason as a plain-text body, not JSON. The status code carries the class of failure and the body carries the message. Do not parse an error response as JSON, and do not expect 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. It carries the message, and where an HTTP equivalent applies it usually begins with that status as a diagnostic aid, so it is worth reading but not worth branching on. 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.

​
401, authentication failed

Note that 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 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 will not help. Contact support@rime.ai if you expect access.

​
429, too many requests

Currently at websocket limit is returned at the WebSocket upgrade when an account opens WebSocket connections faster than Rime allows. Rime does not publish a connection limit, so do not 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.

​
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

Because no response carries a request ID you can quote, 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.