App Server APIs for client applications, including registration and sign-in, group creation, and friend management.
For communication security, the APIs authenticate requests with custom shared headers.
Format
https://$api/$version/$command
| Parameter | Name | Description | |
|---|---|---|---|
| $api | API domain | Available after deploying the service in a private cloud. | |
| $version | Version | API version. | |
| $command | Command | Specific API endpoint. |
Request headers
| Request headers | Required | Description | Notes |
|---|---|---|---|
| appkey | Yes | Unique application identifier. | |
| Authorization | Yes | Obtained from the response after successful sign-in. |
Error code reference
Notes:
- Business APIs usually return HTTP 200. Use
codein the response body to determine success or failure. - The following error codes may be returned by public APIs. Their meanings and typical triggers are derived from server source code (
apis/services/commons/errs).
| code | Constant | Meaning | Typical trigger (derived from source) |
|---|---|---|---|
| 0 | IMErrorCode_SUCCESS | Success | The request was processed successfully. |
| 1 | IMErrorCode_PBILLEGAL | PB parsing failed (internal error code). | Internal use; no direct HTTP API return path is currently identified. |
| 2 | IMErrorCode_DEFAULT | Default error | Generic fallback error; no explicit return path is currently identified, and APP_DEFAULT is used in more cases. |
| 17000 | IMErrorCode_APP_DEFAULT | Application default error | Generic internal fallback error, commonly for database access errors and QR-code generation or query errors. |
| 17001 | IMErrorCode_APP_APPKEY_REQUIRED | Missing appkey | The request header does not include appkey (apis/validate.go). |
| 17002 | IMErrorCode_APP_NOT_EXISTED | Application does not exist or is not configured | The application for appkey does not exist, or the server cannot obtain an IM SDK instance (for example, for sign-in, SMS, email, or QR-code APIs). |
| 17003 | IMErrorCode_APP_REQ_BODY_ILLEGAL | Invalid request body or parameters | JSON parsing failed, a required field is missing, or a parameter format is invalid (for example, account does not match ^[a-zA-Z0-9]{6,20}$ during registration). |
| 17004 | IMErrorCode_APP_INTERNAL_TIMEOUT | Internal service timeout or invocation failure | The server failed or timed out when calling an external dependency such as IM Server (for example, registering with IM Server during sign-in to obtain im_token). |
| 17005 | IMErrorCode_APP_NOT_LOGIN | Not signed in or authentication failed | An authenticated API is missing Authorization, token parsing or validation failed (apis/validate.go), or user creation failed during an SMS or email sign-in flow. |
| 17006 | IMErrorCode_APP_CONTINUE | Continue polling / incomplete | QR-code sign-in: the QR code has not been confirmed (login.go checks whether its state is Default). |
| 17007 | IMErrorCode_APP_QRCODE_EXPIRED | QR code expired | The QR code was created more than 10 minutes ago (login.go). |
| 17008 | IMErrorCode_APP_SMS_SEND_FAILED | Verification code delivery failed | SMS or email verification-code delivery failed, or saving the code record failed (services/smsservice.go, services/mailservice.go, and others). |
| 17009 | IMErrorCode_APP_SMS_CODE_EXPIRED | Verification code invalid or expired | The verification code does not exist, validation failed, or it exceeded the five-minute validity period (used by both SMS and email). |
| 17010 | IMErrorCode_APP_TRANS_NOTRANSENGINE | Translation engine is not configured | A translation API was called without a configured translation engine (services/transservice.go). |
| 17011 | IMErrorCode_APP_USER_EXISTED | User already exists | A write to the user table conflicted during registration or account setup (for example, the account is already in use). |
| 17012 | IMErrorCode_APP_USER_NOT_EXIST | User does not exist | No user was found by account, phone number, email address, or user ID (for example, during account-password sign-in, password changes, or confirmed QR-code sign-in). |
| 17013 | IMErrorCode_APP_LOGIN_ERR_PASS | Incorrect password | Password validation failed (the server compares SHA1(password) with database LoginPass). |
| 17014 | IMErrorCode_APP_PHONE_EXISTED | Phone number already exists | The phone number is already in use during phone binding or setup (services/userservice.go). |
| 17015 | IMErrorCode_APP_EMAIL_EXIST | Email address already exists | The email address is already in use during email binding or setup (services/userservice.go). |
| 17016 | IMErrorCode_APP_Sensitive | Contains sensitive content | Text such as a user nickname or group name contains sensitive words (services/userservice.go, services/groupservice.go). |
| 17100 | IMErrorCode_APP_FRIEND_DEFAULT | Friend default error | Reserved; no explicit return path is currently identified. |
| 17101 | IMErrorCode_APP_FRIEND_APPLY_DECLINE | The other party declined the friend request. | The other party’s friend verification setting declines requests (services/friendservice.go). |
| 17102 | IMErrorCode_APP_FRIEND_APPLY_REPEATED | Repeated friend request | Reserved; no explicit return path is currently identified. |
| 17103 | IMErrorCode_APP_FRIEND_CONFIRM_EXPIRED | Friend confirmation expired | Reserved; no explicit return path is currently identified. |
| 17200 | IMErrorCode_APP_GROUP_DEFAULT | Group default error | Generic group fallback error, for example when a non-owner tries to dissolve a group or a query fails (services/groupservice.go). |
| 17201 | IMErrorCode_APP_GROUP_MEMBEREXISTED | Group member already exists | The applicant is already a group member (services/groupservice.go). |
| 17202 | IMErrorCode_APP_GROUP_NORIGHT | No permission for group operations | Insufficient permissions, for example when validation fails in message or group-management logic (services/messageservice.go, and others). |
| 17300 | IMErrorCode_APP_ASSISTANT_PROMPT_DBERROR | Assistant prompt DB error | Reserved; no explicit return path is currently identified. |
| 17401 | IMErrorCode_APP_FILE_NOOSS | Object storage is not configured | File upload credentials: OSS, Minio, S3, Qiniu, or other storage is not configured (services/fileservice.go). |
| 17402 | IMErrorCode_APP_FILE_SIGNERR | Signature generation failed | File upload credentials: generating a presigned URL or signature failed (services/fileservice.go). |
| 17500 | IMErrorCode_APP_POST_DEFAULT | Moment default error | Generic fallback error for Moment, reaction, and related features (posts/services/reactionservice.go, and others). |
| 17501 | IMErrorCode_APP_POST_NOTEXISTED | Moment does not exist | The Moment does not exist during an update, comment, reaction, or related operation (posts/services/postservice.go, postcommentservice.go). |
| 17502 | IMErrorCode_APP_POST_NORIGHT | No permission for Moment operations | The caller is not the author or lacks permission during an update, comment, reaction, or related operation (posts/services/postservice.go, postcommentservice.go). |