Skip to main content
How a failure looks depends on the host you call. The model hosts on api.rime.ai return a request ID that you can quote to support. The users.rime.ai endpoints return a plain-text message and no request ID.

​
Errors from the model hosts

coda.api.rime.ai and mist.api.rime.ai return these errors: Every successful response carries an x-request-id header, and every JSON error carries the same ID as error.requestId. Log it, and send it to support when you report a problem. The plain-text 400 and the 401 carry no request ID.

​
How failures reach you, per transport

This section and the rest of the page cover the users.rime.ai endpoints. Most of their 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. These responses carry no request ID, so an accurate UTC timestamp is the most useful thing to capture when something fails. Record everything under what to send to support at the moment it happens. 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. The model hosts on api.rime.ai don’t return 406: they stream WAV instead.

​
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 it depends on your plan. See rime.ai/pricing, or for 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

Include all of the following when you report a failure. Redact your API key.
  • The request ID, from the x-request-id header or error.requestId, if the response has one
  • The UTC timestamp of the failure, to the second. Without a request ID, this is how support locates the request
  • The 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.