Skip to main content
For backend integrations, use your server SDK’s structured error fields as the source of truth. Server-side integrations should account for session token failures, WebSocket handshake failures, runtime server errors, and unexpected connection closures.

​
Common Server SDK Error Codes

These stable error codes are useful when building retry, logging, and alerting flows on your backend.
Error codeMeaning
sessionTokenExpiredSession token expired or is no longer authorized
sessionTokenInvalidSession token is invalid or empty
appIDUnrecognizedApp ID is not recognized by the server
appIDMismatchSession token belongs to a different app
avatarNotFoundRequested avatar does not exist
billingRequiredSession is blocked by billing requirements
creditsExhaustedRuntime or connect-time credits are exhausted
sessionDurationExceededSession hit a billing-enforced duration limit
unsupportedSampleRateAudio sample rate is not accepted by the handshake
invalidEgressConfigLiveKit or Agora egress configuration is invalid
egressUnavailableEgress service is unavailable or not configured
idleTimeoutSession was closed because no input was received
upstreamErrorUpstream internal service failed
protocolErrorInvalid protobuf payload or unexpected message sequence
connectionFailedTransport-level connection setup failed
connectionClosedWebSocket closed unexpectedly
serverErrorServer returned an unclassified error
invalidRequestClient request payload or parameters are invalid
unknownFallback code when the SDK cannot classify the failure

​
Server SDK Error Fields

When handling server SDK errors, check these fields to determine the correct recovery path:
  • code: stable SDK error code for programmatic handling
  • phase: where the failure happened, such as session_token, websocket_connect, or websocket_runtime
  • http_status: HTTP status for token or upgrade failures
  • server_code, server_title, server_detail: normalized details returned by the server
  • connection_id, req_id: correlation IDs for tracing requests in logs
  • close_code, close_reason: WebSocket close details for unexpected disconnects
  1. Log code, phase, and correlation IDs (connection_id, req_id).
  2. Retry only transient failures (for example connectionClosed, connectionFailed, idleTimeout).
  3. Surface configuration/auth failures (sessionTokenInvalid, appIDMismatch) to operators.
  4. Alert on recurring upstreamError, serverError, or protocolError.