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.

The WebSocket close-frame reason is limited to 123 bytes. For longer errors, the close reason reads See Error message for details and the full text is delivered in the Error frame above. Read the Error message rather than relying on the close reason.

Close codes

Code	Reason	Description
`3008`	Session Expired: Maximum session duration exceeded	Session exceeded 3 hour limit (or max session duration set by temporary token). You are billed for the full session duration. 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.
`3009`	Unauthorized Connection: Too many concurrent sessions	Streaming rate limit exceeded. For more on rate limits, see your Account’s Rate Limits and how streaming rate limits work.
`1008`	Unauthorized Connection: Missing Authorization header	Missing or invalid API token. Your API tokens can be found on the API Keys page of your account dashboard.
`1008`	Unauthorized Connection: `<reason>`	Account related issue (insufficient account balance, account temporarily disabled, etc.).
`1011`	Internal error	An unexpected server-side error occurred while establishing the connection (for example, during authentication). Retry the connection; if the problem persists, contact support@assemblyai.com.
`410`	Deprecated endpoint	The V2 streaming API has been retired. Use this endpoint instead: `wss://streaming.assemblyai.com/v3/ws`.

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

Handling closed sessionsA 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 support@assemblyai.com with the session id and any further details.

Getting started

Features

API reference

Advanced

Integrations

Guides

Common session errors and closures