Skip to content

Commit

Permalink
ENDOC-288 Channel management error code (#1553)
Browse files Browse the repository at this point in the history 
* ENDOC-288 Channel management error code

* review

* Added missing Blueprint, ReactJS, Unreal Engine platforms.

* review updates - simplified the doc structure

* review updates - language

---------

Co-authored-by: atovpeko <[email protected]>
Co-authored-by: saudsami <[email protected]>
  • Loading branch information
@nirm2009 @atovpeko @saudsami
3 people authored Jul 5, 2024
1 parent a146b92 commit f552d00
Show file tree
Hide file tree
Showing 4 changed files with 197 additions and 65 deletions.
81 changes: 16 additions & 65 deletions shared/video-sdk/reference/_error-codes.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,80 +1,31 @@
import ErrorCodes from '@docs/shared/video-sdk/reference/error-codes/index.mdx';

When interacting with the Agora API, the <Vpd k="SDK" /> may return an error code. Receiving an error code indicates that the SDK has encountered an unrecoverable error that necessitates intervention from your <Vpl k="CLIENT" />.

This page provides descriptions for common error codes along with the associated reasons and their corresponding solutions. For error codes without predefined solutions, <Vg k="COMPANY" /> recommends reaching out to technical support for assistance.

<PlatformWrapper notAllowed="web">
The error codes listed in this section apply to Agora RTC v4.x SDK on the following platforms:

- Native platforms: Android, iOS, macOS, Windows.
- Third-party frameworks (that is, third-party platforms based on native platform encapsulation): Electron, Unity, React Native, Flutter.
</PlatformWrapper>

During the operation of Agora SDK, error codes may be returned in the following ways:

- In the return value of a failed method call.
- Through the `onError` callback.

<Admonition type="info" title="Information">When the SDK returns an error code, it may return a negative number. This negative number corresponds to the positive integer in the error code. For example, a returned value of `-2` corresponds to the error code `2`.</Admonition>

## Common error codes

| Error code | Description |
|:---:|:------------------------------|
| `0` | No error |
| `1` | Generic error (error reasons not clearly classified). Please call the method again. |
| `2` | An invalid parameter was set in the method. For example, the specified channel name contains illegal characters. Please reset the parameter. |
| `3` | The SDK is not ready yet. Generally, the error may be attributed to the following reasons:<ul><li>`RtcEngine` initialization failed. Please reinitialize `RtcEngine`.</li><li>The user has not yet joined the channel when the method is called. Please check the calling logic of the method.</li><li>The user has not left the channel when calling the `rate` or `complain` method. Please check the calling logic of the method.</li><li>The audio module is not turned on.</li><li>The assembly is incomplete.</li></ul> |
| `4` | `RtcEngine` This operation is not supported in the current state. Generally, the error may be attributed to the following reasons:<ul><li>When using built-in encryption, the encryption mode being set is incorrect.</li><li>Failed to load external encryption library. Please check that the encrypted enumeration value is correct, or reload the external encryption library.</li></ul> |
| `5` | Method call rejected. Generally, the error may be attributed to the following reasons:<ul><li>`RtcEngine` initialization failed. Please reinitialize.</li><li>When joining a channel, you set the channel name to a null character `""`. Please reset the channel name.</li><li>In a multi-channel scenario, when calling the `joinChannel` method, the set channel name already exists. Please reset the channel name.</li><li>In a multi-channel scenario, when calling the `joinChannelEx`, the channel name already exists. Please reset the channel name.</li></ul> |
| `6` | The buffer size is not large enough to hold the returned data. |
| `7` | Method is called before `RtcEngine` has been initialized. Please confirm that the `RtcEngine` object has been created and initialized before calling this method. |
| `9` | No operation permission. Please check whether the user has granted the <Vpl k="CLIENT" /> permission to use audio and video devices. |
| `10` | Method call timed out. Some method calls require the SDK to return results. If the SDK takes too long to process the event and does not return for more than 10 seconds, this error occurs. |
| `17` | Joining the channel was denied. Generally, the error may be attributed to the following reasons:<ul><li>The user is already in the channel. Agora recommends using `CONNECTION_STATE_DISCONNECTED` in `onConnectionStateChanged` callbacks to determine whether the user is in the channel. Do not call this method again to join the channel unless the status (1) is received.</li><li>The user started a call test by calling `startEchoTest`, and then tried to join a channel without calling `stopEchoTest`. After starting an echo test, call `stopEchoTest` before joining a channel to end the running test.</li></ul> |
| `18` | Failed to leave channel. Generally, the error may be attributed to the following reasons:<ul><li>The user has already left the channel and called `leaveChannel` again to exit the channel. Just stop calling this method.</li><li>The `leaveChannel` method is called before joining a channel. No additional action is required.</li></ul> |
| `19` | The resource is occupied and cannot be reused. |
| `20` | The SDK gave up the request, possibly due to too many requests. |
| `21` | Certain firewall settings under Windows caused `RtcEngine` initialization to fail and then crash. |
| `22` | The SDK fails to allocate resources, possibly because the <Vpl k="CLIENT" /> takes up too many resources or the system resources are exhausted. |
| `101` | Not a valid App ID. Please use a valid App ID and rejoin the channel. |
| `102` | Not a valid channel name. Please use a valid channel name and rejoin the channel. |
| `103` | `RtcEngine` is unable to obtain server resources for the current region. Please try specifying a different region when initializing. |
| `109` | The current token has expired and is no longer valid. Please generate a new token and call `renewToken` to update. This error code is obsolete. The `CONNECTION_CHANGED_TOKEN_EXPIRED` (9) value in the `onConnectionStateChanged` callback is returned instead. |
| `110` | Token is invalid. Generally, the error may be attributed to the following reasons:<ul><li>The app certificate is enabled in the <Vg k="CONSOLE" />, but app ID plus token authentication is not used. When the app certificate is enabled for the project, token authentication must be used.</li><li>The `uid` used when generating the token is inconsistent with the `uid` used when joining the channel.</li></ul> This error code is obsolete. The `CONNECTION_CHANGED_INVALID_TOKEN` (8) value in the `onConnectionStateChanged` callback is returned instead. |
| `111` | The network connection is interrupted. After the SDK established a connection with the server, the network connection was lost for more than 4 seconds.
| `112` | Network connection lost. The network connection is interrupted and the SDK cannot connect to the server within 10 seconds. |
| `119` | User failed to switch roles, please try to join the channel again. |
| `120` | Decryption failed. It's possible that the user used the wrong password when joining the channel. Please check the password or guide the user to try to rejoin the channel. |
| `121` | The user ID is invalid. |
| `123` | This user is banned from the server. This error is reported when a user is kicked from the server. |
| `134` | Invalid user account. Possible reasons is that invalid parameters are set. |
<PlatformWrapper platform="web">
- For asynchronous methods, the SDK returns a Promise to notify the result of the asynchronous operation, and the SDK throws the appropriate error code when the Promise is rejected.
- When a synchronous method call fails, the SDK throws an error code directly.
The SDK may also throw some network related error codes during internal operation.

The SDK's error object `AgoraRTCError` inherits from the browser's [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object. Print out the error code on the console via `AgoraRTCError.code` since directly printing the `AgoraRTCError` object will only show the error message.
</PlatformWrapper>

## Audio-related error codes

| Error code | Description |
|:---:|:------------------------------|
| `1005` | An audio device error occurred (unspecified error). Please check whether the audio device is occupied by another application, or try to re-enter the channel. |
| `1008` | An error occurred while initializing the playback device. Please check whether the playback device is occupied by another application, or try to re-enter the channel. |
| `1009` | Error starting playback device. Please check whether the playback device is working normally. |
| `1010` | Error stopping playback device. |
| `1011` | An error occurred while initializing the recording device. Please check whether the recording device is working normally, or try to re-enter the channel. |
| `1012` | Error starting recording device. Please check whether the recording device is working normally. |
| `1013` | An error occurred while stopping the recording device. |


## Data flow related error codes​

| Error code | Description |
|:---:|:------------------------------|
| `113` | The user was not in the channel when the `sendStreamMessage` method was called. |
| `114` | When calling `sendStreamMessage`, the length of data sent is greater than 1024 bytes. |
| `115` | When calling `sendStreamMessage`, the frequency of sending data exceeds the limit (6 KB/s). |
| `116` | When calling `createDataStream`, the number of data streams created is more than limit (5). |
| `117` | Data stream sending timed out. |
<PlatformWrapper notAllowed="web">
- In the return value of a failed method call.
- Through the `onError` callback.

## Other error codes
<Admonition type="info" title="Information"><ul><li>When the SDK returns an error code, it may return a negative number. This negative number corresponds to the positive integer in the error code. For example, a returned value of `-2` corresponds to the error code `2`.</li><li>The API names on this page are based on C++. The API names of other platforms may be different. Please refer to the API documentation of the corresponding platform.</li></ul></Admonition>
</PlatformWrapper>

| Error code | Description |
|:---:|:------------------------------|
| `130` | The SDK does not support pushing encrypted streams to a CDN. |
| `1001` | Failed to load media engine. |
| `1501` | No camera access. Please check whether the camera permission has been granted. |
<ErrorCodes />
10 changes: 10 additions & 0 deletions shared/video-sdk/reference/error-codes/index.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
import NonWebErrorCodes from './non-web-error-codes.mdx'
import WebErrorCodes from './web-error-codes.mdx'

<PlatformWrapper platform="web">
<WebErrorCodes />
</PlatformWrapper>

<PlatformWrapper notAllowed="web">
<NonWebErrorCodes />
</PlatformWrapper>
62 changes: 62 additions & 0 deletions shared/video-sdk/reference/error-codes/non-web-error-codes.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
## Common error codes

| Error code | Description |
|:--:|:------------------------------|
| `0` | No errors. |
| `1` | General error (no clearly categorized cause of error). Please call the method again. |
| `2` | An invalid parameter was set in the method. For example, the specified channel name contains illegal characters. Please reset the parameters. |
| `3` | The SDK is not ready yet. There are usually the following reasons: <ul><li>`RtcEngine` initialization failed. Please reinitialize `RtcEngine`.</li> <li>The user has not joined the channel when the method is called.</li> <li>Please check the calling logic of the method.</li> <li>The user has not left the channel when the `rate` or `complain` method is called, please check the method calling logic.</li> <li>Audio module is not enabled.</li> <li>Incomplete assembly.</li></ul> |
| `4` | The current state of `RtcEngine` does not support this operation. There are generally the following reasons: <ul><li>Incorrect encryption mode set when using built-in encryption.</li> <li>Failed to load external encryption library. Please check if the enumeration value for encryption is correct, or reload the external encryption library.</li></ul> |
| `5` | The method call is rejected. There are generally the following reasons: <ul><li>`RtcEngine` initialization failed. Please reinitialize `RtcEngine`.</li> <li>The channel name was set to the empty character "" when joining a channel. Please reset the channel name.</li> <li>In a multi-channel scenario, the channel name set when the `joinChannel` method was called to join a channel already exists. Please reset the channel name.</li> <li>In a multi-channel scenario, the channel name set when the `joinChannelEx` method is called to join a channel already exists. Please reset the channel name.</li></ul> |
| `6` | The buffer size is not large enough to hold the returned data. |
| `7` | The method is called before `RtcEngine` is initialized. Please make sure that the `RtcEngine` object has been created and initialized before calling the method. |
| `9` | There is no permission to operate. Please check whether the user has granted the app permission to use audio/video devices. |
| `10` | Method call timed out. Some method calls require the SDK to return results, and this error occurs if the SDK takes too long to process the event and does not return for more than 10 seconds. |
| `17` | Joining a channel is rejected. There are usually the following reasons: <ul><li>The user is already in the channel. <Vg k="COMPANY" /> recommends using the `onConnectionStateChanged` callback to determine if the user is in the channel. Do not call this method again to join the channel unless you receive a `CONNECTION_STATE_DISCONNECTED(1)` status.</li> <li>A user who calls `startEchoTest` for a call test tries to join the channel without calling `stopEchoTest` to end the current test. After starting a call test, you need to call `stopEchoTest` to end the current test before joining the channel.</li></ul> |
| `18` | Failed to leave the channel. There are generally the following reasons: <ul><li>The user has already left the channel, and this error is returned when the method to exit the channel, such as `leaveChannel`, is called again. Stop calling this method.</li> <li>The exit channel method such as `leaveChannel` is called when the user has not joined the channel yet. No additional action is needed in this case.</li></ul> |
| `19` | The resource is occupied and cannot be reused. |
| `20` | The SDK abandons the request, possibly due to too many requests. |
| `21` | Specific firewall settings on Windows cause the `RtcEngine` initialization to fail and then crash. |
| `22` | The SDK failed to allocate resources, possibly because the app takes up too many resources or the system resources are exhausted. |
| `101` | Not a valid App ID, please rejoin the channel with a valid App ID. |
| `102` | Not a valid channel name. The possible reason is that the parameter data type set is incorrect. Please rejoin the channel with a valid channel name. |
| `103` | Cannot get server resources for the current region. Please try to specify a different region when initializing `RtcEngine`. |
| `109` | The currently used Token has expired and is no longer valid. Please generate a new Token on the server side and call `renewToken` to update the Token. <Admonition type="info" title="Deprecated">This error code is deprecated. Please use `CONNECTION_CHANGED_TOKEN_EXPIRED(9)` in the `onConnectionStateChanged` callback instead. </Admonition> |
| `110` | Token is invalid. There are generally the following reasons: <ul><li>App certificate is enabled in the <Vg k="CONSOLE" />, but App ID + Token authentication is not used. When App certificate is enabled in the project, you must use Token authentication.</li> <li>The `uid` field entered when generating the Token does not match the `uid` entered when the user joined the channel.</li></ul> <Admonition type="info" title="Deprecated">This error code is deprecated. Please use `CONNECTION_CHANGED_INVALID_TOKEN(8)` in the `onConnectionStateChanged` callback instead.</Admonition> |
| `111` | The network connection is interrupted. After the SDK established a connection with the server, the network connection was lost for more than 4 seconds. |
| `112` | Network connection lost. The network connection was interrupted and the SDK could not connect to the server within 10 seconds. |
| `119` | User failed to switch roles, please try to join the channel again. |
| `120` | Decryption failed. It is possible that the user used the wrong password when joining the channel. Please check the password the user entered when joining the channel, or direct the user to try to rejoin the channel. |
| `121` | The user ID is invalid. |
| `123` | This user has been banned by the server. This error is reported when the user is kicked out by the server. |
| `134` | Invalid user account, possibly because invalid parameters are set. |

## Audio-related error codes

| Error code | Description |
|:--:|:------------------------------|
| `1005` | An unspecified error occurred in the audio device. Check if the audio device is occupied by another application or try to re-enter the channel. |
| `1008` | An error occurred while initializing the playback device. Check if the playback device is occupied by another application or try to re-enter the channel. |
| `1009` | Error starting the playback device. Please check if the playback device is working properly. |
| `1010` | Error stopping the playback device. |
| `1011` | Error initializing the recording device. Please check if the recording device is working properly, or try to re-enter the channel. |
| `1012` | Error starting the recording device. Please check if the recording device is working properly. |
| `1013` | Error stopping the recording device. |

## Data stream-related error codes

| Error code | Description |
|:--:|:------------------------------|
| `113` | The user was not in the channel when the `sendStreamMessage` method was called. |
| `114` | When `sendStreamMessage` was called, the length of the data sent was greater than 1024 bytes. |
| `115` | The frequency of sending data exceeded the limit (6 KB/s) when calling `sendStreamMessage`. |
| `116` | Number of data streams exceeding the limit (5) were created when `createDataStream` was called. |
| `117` | Data stream send timeout. |

## Other error codes

| Error code | Description |
|:--:|:------------------------------|
| `130` | The SDK does not support pushing encrypted streams to a CDN. |
| `1001` | Failed to load the media engine. |
| `1501` | There is no permission to use the camera. Please check if camera permission has been turned on. |
Loading

0 comments on commit f552d00

Please sign in to comment.