Platform API

Error codes

OpenIM REST APIs use a common error response envelope. A request may return HTTP 200 OK and still fail at the business layer, so always check errCode; errCode === 0 means the operation succeeded.

Response structure

{
  "errCode": 1001,
  "errMsg": "ArgsError",
  "errDlt": "request body or header is invalid"
}

Field	Type	Description
errCode	int	OpenIM business error code. `0` means success.
errMsg	string	Short error message for logs and diagnostics.
errDlt	string	Detailed error text for parameter, permission, or server-state troubleshooting.
data	object	Successful responses may include endpoint-specific data.

Error code ranges

Range	Source	Description
0	Common success code	The business operation succeeded.
1-9999	OpenIM server errors	Main REST API and server-side error range.
10000-20000	OpenIM client errors	SDK or client runtime errors, not expanded as server Platform API codes.
20001-29999	Business webhook errors	Custom backend errors returned by webhook or business logic.

Handling flow

Check the HTTP status first for network, gateway, or infrastructure failures.
Parse the JSON response and use errCode as the business success flag.
When errCode !== 0, log operationID, endpoint path, request summary, errCode, errMsg, and errDlt.
Fix authentication, permission, and parameter errors before retrying.
Convert internal error details into product-safe messages before showing them to end users.

Server error codes

Code	Category	Meaning	Recommended action
0	Success	Success	Continue reading endpoint-specific `data`.
500	Server	Internal server error	Check OpenIM services, dependencies, and internal networking.
1001	Request	Invalid arguments	Check headers, JSON types, required fields, and enum values.
1002	Request	Permission denied	Confirm that `token` is a valid administrator token and the operation is authorized.
1003	Request	Duplicate primary key	Check whether the user, group, or business ID was already submitted.
1004	Request	Record not found	Confirm that the target user, group, message, or relationship exists.
1101	User	User ID does not exist	Register or import the user before calling dependent APIs.
1102	User	User already registered	Treat repeated registration as idempotent success or a business conflict.
1201	Group	Group does not exist	Confirm that `groupID` exists and has not been dismissed.
1202	Group	Group already exists	Use another `groupID` or check whether creation already succeeded.
1203	Group	User is not in the group	Confirm membership before member-level operations.
1204	Group	Group dismissed	Stop group operations and sync business-side group state.
1205	Group	Unsupported group type	Check that `groupType` is supported by the deployment.
1206	Group	Group application already processed	Make join-request handling idempotent.
1301	Relationship	Cannot add yourself as a friend	Reject self-targeted friend operations before calling OpenIM.
1302	Relationship	Blocked by the other user	Resolve blacklist state before continuing friend workflows.
1303	Relationship	The target user is not a friend	Establish the relationship before friend-dependent operations.
1304	Relationship	Already friends	Treat the existing relationship as success.
1401	Message	Read status is disabled	Avoid workflows that depend on read status when the feature is off.
1402	Message	Member is muted	Check the member mute end time or unmute before sending.
1403	Message	Group is muted	Unmute the group before sending.
1404	Message	Message already revoked	Sync message state in the business system.
1405	Message	Authorization expired	Refresh the related credential and retry.
1501	Token	Token expired	Refresh or issue a new token.
1502	Token	Token invalid	Reissue the token and check signing keys, user ID, and platform.
1503	Token	Token format error	Check whether the token string was truncated or encoded incorrectly.
1504	Token	Token not active yet	Check server time and token effective time.
1505	Token	Unknown token error	Log full details and reissue the token.
1506	Token	Token was kicked	Ask the client to log in again.
1507	Token	Token missing	Confirm that the request header or login payload includes a token.
1601	Connection	Too many gateway connections	Check gateway limits and scale or clear abnormal connections.
1602	Connection	Invalid connection handshake	Check platform ID, user ID, token, and client version.
1701	File	Upload expired	Initialize upload again and use fresh credentials.

Troubleshooting

Scenario	Recommendation
Error cannot be reproduced	Use the same `operationID` across business logs, OpenIM API logs, and gateway logs.
Many `1001` errors	Check JSON field types, required fields, pagination, and headers.
Many `1002` or `1501-1507` errors	Review administrator token issuing, refresh, and storage logic.
Group or member errors	Confirm `groupID`, member role, group state, and operator permission before retrying.
File upload errors	Initialize upload again and verify object name, signature, and expiration time.

Was this page helpful?