Common session errors and closures

Common session errors and closures

In WebSocket based connections, closures and errors represent different ways a connection can terminate. A closure is a normal, expected termination initiated by either the client or the server, whereas errors are terminations resulting from an unexpected problem like network issues, protocol mismatches, timeouts, or server-side issues. In the event of an error, the on_error callback is triggered just prior to on_close. If an error is not encountered, then only on_close is called.

When a session closes, the on_close callback receives a status code and reason detailing why the connection ended. This information is useful when attempting to debug issues or handle certain closure scenarios programmatically. The below table lists some of the common reasons for a session closure along with their corresponding codes and descriptions.

The Error message

When a session ends because of an error (rather than a normal closure), the server sends an Error text frame immediately before it closes the WebSocket. The frame carries the close code and a human-readable message:

{
  "type": "Error",
  "error_code": 3008,
  "error": "Session Expired: Maximum session duration exceeded"
}

Field	Type	Description
type	string	Always "Error".
error_code	integer	The error code. The WebSocket then closes with this same value as its close code.
error	string	Human-readable description of what went wrong.

When the server sends the Error frame, the close reason is always See Error message for details, whatever the length of the error, and the full text is in the Error frame above. The close reason carries the error text itself, cut to 123 bytes (the most a close frame can hold), only if the Error frame could not be sent. Read the Error message rather than relying on the close reason.

Close codes

The Error text column shows the error field of the Error message that comes before the close.

Code	Error text	Description
3008	Session Expired: Maximum session duration exceeded	Session exceeded 3 hour limit (or max session duration set by temporary token). The session closes after the current turn ends, or up to 60 seconds after the limit. You are billed for the full session duration, including this extra time. Always terminate sessions explicitly to control costs.
3007	Input duration violation: <time> ms. Expected between 50 and 1000 ms	Audio chunk size less than 50ms or greater than 1000ms.
3006	Invalid Message Type: <message>	Unsupported message type.
3006	Invalid JSON: <json>	Message contains invalid JSON.
3006	Invalid Message: <message>	Message is not valid (i.e. '[]').
3006	Session terminated due to inactivity: No messages received for <n> seconds	The inactivity_timeout you configured elapsed with no audio or messages. Send a KeepAlive message to reset the timer if you need to hold the session open during silence.
3007	Audio Transmission Rate Exceeded: Received <time> sec. audio in <time> sec	Audio sent faster than real-time.
3005	Session Cancelled: An error occurred	Unknown server error.
1008	Unauthorized Connection: Too many concurrent sessions	Your account opened more new sessions this minute than its streaming rate limit allows. Despite the wording, the limit counts session starts per minute, not open sessions. Back off and open the session again in the next minute. For more on rate limits, see your Account’s Rate Limits and how streaming rate limits work.
1008	Unauthorized Connection: Missing Authorization header	No API key or temporary token was sent. Your API keys can be found on the API Keys page of your account dashboard.
1008	Unauthorized Connection: Invalid API key	The API key or temporary token is not valid. Check the key on the API Keys page of your account dashboard.
1008	Unauthorized Connection: Signature has expired	The temporary token expired before it opened a session. Create a new temporary token and connect with it.
1008	Unauthorized Connection: Insufficient funds	Your account balance is too low. Add funds before reconnecting.
1008	Unauthorized Connection: API key is disabled	The API key, its project or the account is disabled. Use an enabled key, or contact [e-mail].
1008	Unauthorized Connection: No metronome account found	The account’s billing is not set up. Contact [e-mail].
1011	Error authenticating connection	An unexpected server-side error occurred while establishing the connection (for example, during authentication). Retry the connection; if the problem persists, contact [e-mail].

Deciding whether to retry a 1008

Code 1008 covers both the streaming rate limit and credential or account problems, so the code alone does not tell you whether retrying can help. Decide from the error text of the Error message: retry with backoff only on Unauthorized Connection: Too many concurrent sessions, in the next minute. For any other 1008 text, fix the key, token or account first; reconnecting unchanged fails again.

Code 3005 is still used as a catch-all for server-side errors not covered by the more specific codes above.

Connecting to the retired V2 streaming endpoint fails with HTTP status 410 on the upgrade request. This is an HTTP status, not a WebSocket close code. Use this endpoint instead: wss://streaming.assemblyai.com/v3/ws.

Handling closed sessions

A common way to handle a closure such as 3008 - Session Expired: Maximum session duration exceeded is to parse the status code and reason in the on_close callback. If a specific code and reason are detected, you can then take appropriate action, such as opening a new session or logging useful debugging information.

Note that the on_error callback is not triggered in this case, as the session closes for a known reason and not due to encountering an error.

If you believe your session received an error or closed due to a reason not listed above, please reach out to [e-mail] with the session id and any further details.