Error Handling
This section is an overview of error conditions, how the Web broadcast SDK reports them to the application, and what an application should do when those errors are encountered. Errors are reported by the SDK to listeners of the StageEvents.ERROR
event:
stage.on(StageEvents.ERROR, (error: StageError) => {
// log or handle errors here
console.log(`${error.code}, ${error.category}, ${error.message}`);
});
Stage Errors
A StageError is reported when the SDK encounters a problem it cannot recover from and generally requires app intervention and/or network reconnection to recover.
Each reported StageError
has a code (or StageErrorCode
), message (string), and category (StageErrorCategory
). Each is related to an underlying operation category.
The operation category of the error is determined based on whether it is related to the connection to the stage (JOIN_ERROR
), sending media to the stage (PUBLISH_ERROR
), or receiving an incoming media stream from the stage (SUBSCRIBE_ERROR
).
The code property of a StageError
reports the specific problem:
Name | Code | Recommended Action |
---|---|---|
TOKEN_MALFORMED | 1 | Create a valid token and retry instantiating the stage. |
TOKEN_EXPIRED | 2 | Create an unexpired token and retry instantiating the stage. |
TIMEOUT | 3 | The operation timed out. If the stage exists and the token is valid, this failure likely is a network issue. In that case, wait for the device’s connectivity to recover. |
FAILED | 4 | A fatal condition was encountered when attempting an operation. Check error details. If the stage exists and the token is valid, this failure likely is a network issue. In that case, wait for the device’s connectivity to recover. |
CANCELED | 5 | Check application code and ensure there are no repeated join , refreshStrategy , or replaceStrategy invocations, which may cause repeated operations to be started and canceled before completion. |
STAGE_AT_CAPACITY | 6 | Try the operation again when the stage is no longer at capacity, by refreshing the strategy. |
CODEC_MISMATCH | 7 | The codec is not supported by the stage. Check the browser and platform for codec support. For IVS real-time streaming, browsers must support the H.264 codec for video and the Opus codec for audio. |
TOKEN_NOT_ALLOWED | 8 | The token does not have permission for the operation. Recreate the token with the correct permission(s) and try again. |
Handling StageError Example
Use the StageError code to determine if the error is due to an expired token:
stage.on(StageEvents.ERROR, (error: StageError) => {
if (error.code === StageError.TOKEN_EXPIRED) {
// recreate the token and stage instance and re-join
}
});
Network Errors when Already Joined
If the device’s network connection goes down, the SDK may lose its connection to stage servers. You may see errors in the console because the SDK can no longer reach backend services. POSTs to https://broadcast.stats.live-video.net will fail.
If you are publishing and/or subscribing, you will see errors in the console related to attempts to publish/subscribe.
Internally the SDK will try to reconnect with an exponential backoff strategy.
Action: Wait for the device’s connectivity to recover.
Errored States
We recommend you use these states for application logging and to display messaging to users that alerts them of connectivity issues to the stage for a particular participant.
Publish
The SDK reports ERRORED
when a publish fails.
stage.on(StageEvents.STAGE_PARTICIPANT_PUBLISH_STATE_CHANGED, (participantInfo, state) => {
if (state === StageParticipantPublishState.ERRORED) {
// Log and/or display message to user
}
});
Subscribe
The SDK reports ERRORED
when a subscribe fails. This can occur due to network conditions or if a stage is at capacity for subscribers.
stage.on(StageEvents.STAGE_PARTICIPANT_SUBSCRIBE_STATE_CHANGED, (participantInfo, state) => {
if (state === StageParticipantSubscribeState.ERRORED) {
// Log and/or display message to user
}
});