Client SDK error codes
Identify common OpenIMClientSDK error codes, distinguish their source, and apply safe handling guidance.
Scope
This page lists the common client error codes used by OpenIMClientSDK. The iOS, Android, Flutter, WASM, and Electron SDKs expose failures through different callbacks, exceptions, or rejected promises, but errors returned by OpenIM SDK Core retain the same meaning. Platform wrappers, operating systems, and runtimes can still add errors that are not listed here, so always retain the error message and client SDK version.
A client call can also return a business error from OpenIMServer. Do not interpret every failure as a client error; identify its source first.
Identify the error source
| Code | Source | How to handle it |
|---|---|---|
0 | Common success code | The business operation succeeded. Continue reading the data returned by the API. |
1-9999 | OpenIMServer | Use the Platform API error code reference to diagnose parameters, permissions, tokens, groups, or message state. |
Codes from 10000 through 10401 listed on this page | OpenIMClientSDK | Diagnose client networking, lifecycle state, local data, and operation preconditions. The codes are not contiguous; do not infer meanings for undefined values. |
20001-29999 | Business server or webhook | These codes are defined by the integrating business system. Maintain their meanings and user-facing messages in that backend. |
Common and session errors
| Code | Meaning | Recommended action |
|---|---|---|
10000 | Network request failed | Check device connectivity, API and WebSocket addresses, TLS certificates, and proxy configuration. Retry after connectivity is restored. |
10001 | Network request timed out | Check network quality and service health. For a state-changing operation, query its actual result before retrying. |
10002 | Invalid arguments | Check required fields, data types, enum values, and mutually exclusive parameters against the current API page. |
10003 | The call context timed out or was canceled | Check caller timeouts, page or task lifecycle, and whether login state changed while the call was running. |
10004 | Resource initialization is incomplete | This code can be returned by client versions that still define it. Wait for initialization and login to finish before calling an API that depends on local resources. |
10005 | Unrecognized error | Retain the error message, SDK version, and API name. Confirm reproducible steps before upgrading or submitting diagnostic information. |
10006 | Internal SDK error | Collect client logs and a minimal reproduction, then verify SDK compatibility. Do not display internal details directly to end users. |
10007 | No update is available | The synchronization or update produced no new data. Keep the current state and decide whether to refresh based on the API's documented behavior. |
10008 | SDK is not initialized | Complete the platform's SDK initialization flow and wait for success before calling other APIs. |
10009 | SDK login is incomplete | Wait for login success before calling authenticated APIs, and avoid concurrent or repeated login attempts. |
10100 | User ID does not exist or is not registered | Confirm that a trusted backend registered the user with OpenIMServer and that the client uses the correct userID. |
10101 | The user has logged out | Stop authenticated calls and clear session state. Obtain a new token and sign in again if the client should continue. |
10102 | Repeated login | Do not start another login while the previous attempt is still active. Reuse the current SDK instance, or log out before changing accounts. |
Message errors
| Code | Meaning | Recommended action |
|---|---|---|
10200 | File not found | Check the local path, temporary-file lifetime, and read permissions before recreating or uploading the file message. |
10201 | Message decompression failed | Verify client and server compatibility and synchronize the message again. Retain logs if the same data continues to fail. |
10202 | Binary WebSocket message decoding failed | Verify the client and server protocol versions and check whether a proxy is modifying WebSocket data. |
10203 | Message or binary protocol type is unsupported | Use a message type supported by the current SDK and verify client-server version compatibility. |
10204 | The message cannot be sent again | Only the original failed message can be resent. Create a new message object if an already successful message must be sent again. |
10205 | Message content type is unsupported | Use a supported type, or implement the corresponding custom-message handling on both the client and server. |
10206 | The message has no server sequence number | The message is not ready for an operation that requires seq. Wait for sending or synchronization to finish and retry with the latest message object. |
10207 | The message has been deleted | Remove it from UI and business state. Do not continue modifying, revoking, or querying the stale message object. |
Conversation and group errors
| Code | Meaning | Recommended action |
|---|---|---|
10301 | The current conversation or group type does not support the operation | Check the API's supported conversation and group types, and do not apply it to an unsupported group. |
10302 | The operation supports only a specific group type | Check the target's groupType and use an API that matches that group type. |
10303 | The current unread count is already 0 | Refresh the UI from the latest conversation state instead of decrementing or clearing the count again. |
10400 | Group ID not found | Check the groupID, retrieve the group again, and confirm that it has not been dismissed. |
10401 | Invalid group type | Use a group type supported by the current SDK and OpenIMServer, and verify the groupType returned during creation or retrieval. |
Version compatibility
Error definitions evolve with client SDK releases. Code 10004 exists in some released versions, while the current OpenIM SDK Core distinguishes initialization and login readiness with 10008 and 10009. Applications that support older clients can continue recognizing 10004; new handling should distinguish an uninitialized SDK from an incomplete login.
Do not automatically classify an integer that is absent from this page as a client error. First determine whether it came from the client, OpenIMServer, or a business webhook, then use the current SDK version's error message and release notes.
Handling recommendations
- Record the code, message, API name, client SDK version, and necessary target identifiers. Redact tokens, full message bodies, and other sensitive data.
- Correct invalid parameters, session state, or unsupported preconditions instead of retrying automatically.
- Use backoff for network failures and timeouts. Before retrying messages or other state changes, query or synchronize actual state to avoid duplicate operations.
- Map technical errors to stable product messages rather than exposing internal details to end users.
- If
10005,10006, or decoding errors persist, retain complete logs and follow the platform guide for WASM logging, iOS logging, Flutter logging, or Electron log upload.
This page was migrated from the legacy client error code reference and verified against the current OpenIM SDK Core definitions and the compatibility definitions.
Was this page helpful?