Constraints, Rate Limits And Errors

Properties and Constraints:

API Keys: Properties and Constraints

Item	Property or Constraint	Notes
API Keys	100 characters (UTF8mb4 Characters)	This covers all the languages and even emojis. (One emoji uses two characters).
Maximum number of APIs keys that can be created for an app	25	Contact support if you need additional API keys for your application.

Users and Groups: Properties and Constraints

Item	Property or Constraint	Notes
Character limits for UIDs and GUIDs	100 characters	Use alphanumeric characters with dashes only; spaces are not allowed.
Maximum users in a group (with all features)	300	Groups up to 300 members support all features including delivery/read receipts and typing indicators.
Maximum users in a group (without delivery & read receipts)	50,000 (up to 10,000 concurrent)	Large groups disable delivery/read receipts and typing indicators for performance.
Maximum groups a user can be a part of	2000	Users exceeding this limit must leave existing groups before joining new ones.
Maximum number of friends for a user	1000	Friend relationships are bidirectional and count toward both users’ limits.
Maximum tokens for a user	No limits	Multiple auth tokens allow users to stay logged in across different devices.
Maximum Number of Bot users that can be created	25	Bot users are special accounts for automated messaging and integrations.
Bot UID character limit	50 characters	Bot UIDs have a shorter limit than regular user UIDs.
Maximum number of groups	No limits	Create as many groups as needed; billing is based on active users.
Maximum number of unread messages per user	No limits	Unread counts are tracked per conversation for accurate badge displays.
Maximum number of users that can be created for an app	No limits	User creation is unlimited; pricing is based on Monthly Active Users (MAU).
User and Group ID	100 characters, alpha-dash (a-z, 0-9 with -and _) without spaces .	CometChat forces the UID to all lowercase.
User and Group name	100 characters, UTF8mb4 set	This covers all the languages and even emojis.
User and Group avatar	Must be a URL, limit of 3000 characters	CometChat doesn’t save the image on its servers.. There is no limit on the image resolution. It depends on the implementation.
User profile	Must be a URL, limit of 3000 characters	Same as above
User and Group metadata	The API limit for the POST request length is 10 KB. Hence, the user’s metadata information must fit in the same limit and must not exceed 5 KB.	Use metadata to store custom key-value pairs for users and groups.
User and Group tag	A user can have up to 25 tags with 100 characters per tag. The tags can be in any language. The character set must be UTF8mb4	Tags enable filtering and searching users/groups by custom categories.
Group password	String up to 100 characters	Only applicable for password-protected group types.
Group description	255 characters, UTF8mb4 set	Provide a brief summary of the group’s purpose for members.
Maximum active presence subscriptions	The presence subscription will be active until 1000 users are online for a single app. if more than 1000 users go online, the presence notification starting from the 1001st user will not be sent to other users.	Note, this is the higher limit applicable across subscription for friends, users with certain roles and all users
Typing indicators for groups	Typing indicator will be sent for a group of up to 1000 online users.	Disabled for larger groups to optimize real-time performance.
Unread message counts for groups	For a group with more than 300 members, the conversations and unread message counts are not updated.	Use message history APIs to track read status in large groups.
Delivery and read receipts for groups	Delivery and read receipts will be sent for a group of up to 300 online users.	Receipts are disabled in large groups to reduce server load.

Roles: Properties and Constraints

Item	Property or Constraint	Notes
Maximum number of Roles that can be created	Maximum 25	Roles define permissions and access levels for users.
Role UID	100 characters, alpha-dash (a-z, 0-9 with -and _) without spaces	CometChat forces the UID to lowercase.
Role name	100 characters, UTF8mb4	This covers all the languages and even emojis.
Role description	255 characters, UTF8mb4 set, any language.	Describe the role’s purpose and permissions clearly.
Metadata	No limit	Store additional role configuration as JSON key-value pairs.

Messages: Properties and Constraints

Item	Property or Constraint	Notes
Maximum message size	65 KB (~65,536 characters including metadata)	Total size limit for the entire message payload.
File size	Maximum file size per message: 100 MB	Applies to the uploaded file associated with the message.
Message Data	Arbitrary JSON (UTF-8/utf8mb4), up to 10 KB for the data object; keys with special meaning to CometChat: text, attachments, customData, metadata	Attachment properties (for example, URL and size) can be included here; the actual file limit is defined under File size.
Groups → Unread message count	For groups with more than 300 members, conversation and unread message counts are not updated	Use message history APIs to track read status in large groups.
Groups → Mark as unread	For groups with more than 300 members, the unread message counts are not updated	Feature disabled for performance optimization in large groups.
Groups → Message receipts	Delivery and read receipts are sent for groups with up to 300 members	Receipts are disabled in large groups to reduce server load.
Tags	Up to 25 tags per message; 100 characters per tag (UTF-8/utf8mb4)	Tags can be in any language.
User mentions	Up to 10 distinct users can be mentioned in a message	Format: <@uid:{uid of the user}> (example: <@uid:cometchat-uid-1>).
Reactions	Maximum 25 distinct reactions per message; reaction text up to 45 characters (UTF-8/utf8mb4)	Character counts are by Unicode code points. Emoji are supported and may use multiple code points.

Calling: Properties and Constraints

Item	Property or Constraint	Notes
Maximum users in a call	50	Supports both one-on-one and group calling scenarios and it works the best with 50.
Default frame rate for video calls	30 FPS	Frame rate may adapt based on network conditions.
Resolution for video calls	Maximum - 720p, Minimum - 180p	This depends on the layout selected and the bandwidth available at the user’s end
Media encryption used	SRTP	Ensures secure real-time communication for all calls.
Audio codec used	OPUS	Optimized for low-latency voice communication.
Video codec used	H.264	Widely supported codec for cross-platform compatibility.

Webhooks: Properties and Constraints

Item	Property or Constraint	Notes
Webhook URL	Valid URL, maximum 255 characters	Must be a publicly accessible HTTPS endpoint.
Webhook ID	50 characters, UTF8mb4 set, alphanumeric (without spaces)	Unique identifier used to manage and reference the webhook.
Webhook authentication username	50 characters, alphanumeric (without spaces)	Used for HTTP Basic Authentication when calling your endpoint.
Webhook authentication password	100 characters, alphanumeric (without spaces)	Keep this secure; used to verify webhook requests to your server.

Rate Limits

Operation Type	Rate Limit	Examples / Notes
Core operations	10,000 requests/min	User connection, create/delete user, create/join/leave group
Standard operations	20,000 requests/min	All other operations (sending messages, fetching conversations, updating profiles)
Build plan (free)	500 requests/min	Applies to both core and standard operations
Send message	30 messages/min	Per user rate limit for sending messages
Mark as unread	5 requests/min	Per user rate limit for marking messages as unread
Data import	60 requests/min	Rate limit for bulk data import operations

Errors

Error Code	Error Description
Auth Errors
AUTH_ERR_EMPTY_APPID	Indicates empty appId in the headers.
AUTH_ERR_INVALID_APPID	Indicates invalid appId or it does not exist in a region.
AUTH_ERR_EMPTY_APIKEY	Indicates empty API Key in the headers.
AUTH_ERR_APIKEY_NOT_FOUND	Indicates incorrect API Key in the headers.
AUTH_ERR_NO_ACCESS	Indicates API Key in the headers can not be used to perform the action. For example, the API key with authOnly scope cannot be used to create a user.
AUTH_ERR_EMPTY_AUTH_TOKEN	Indicates empty auth token in the headers.
AUTH_ERR_AUTH_TOKEN_NOT_FOUND	Indicates incorrect auth token.
API Key Errors
ERR_APIKEY_NOT_FOUND	Indicates that the api key does not exists.
ERR_APIKEY_NO_SELF_ACTION	Indicates that the API key in the headers is same as the API key in the path param and it is performing action on it self. The API Key should not update/delete itself.
Auth Token Errors
ERR_AUTH_TOKEN_NOT_FOUND	Indicates that the auth token does not exists.
ERR_AUTH_TOKEN_DELETE_FAILED	Indicates that the API failed to delete the auth token.
ERR_AUTH_TOKENS_DELETE_FAILED	Indicates that the API failed to delete the auth tokens associated with the UID
ERR_AUTHTOKEN_UNAVAILABLE	Indicates that the auth token is mapped with another device.
ERR_AUTHTOKEN_NOT_ACCESSIBLE	Indicates that the auth token is mapped with another user.
Subscription Errors
ERR_PLAN_RESTRICTION	Indicates that the feature is not available with the plan.
ERR_SUBSCRIPTION_EXPIRED	Indicates that the subscription has expired and must resubscribe to continue using the service.
ERR_PLAN_QUOTA_RESTRICTION	Indicates that the allowed limit for the feature has reached.
Role Errors
ERR_ROLE_NOT_FOUND	Indicates that the role does not exist.
ERR_ROLE_DELETE_FAILED	Indicates that the API failed to delete the role.
ERR_ROLE_DELETE_DENIED	Indicates that the API cannot delete the role as the default role can not be deleted.
User Errors
ERR_UID_NOT_FOUND	Indicates any one of the following: 1. UID does not exist. 2. User is soft deleted.
ERR_UID_DELETE_FAILED	Indicates that the API failed to delete the user.
Bots Errors
ERR_BOT_NOT_FOUND	Indicates that a bot is not associated with the UID.
ERR_BOT_ALREADY_EXISTS	Indicates that a bot is already associated with the UID.
Group Errors
ERR_GUID_NOT_FOUND	Indicates that the GUID does not exist.
ERR_EMPTY_GROUP_PASS	Indicates one from the below: 1. Empty password for password type group to create group API. 2. Empty password for pasword type group to join group API.
ERR_GROUP_DELETE_FAILED	Indicates that the API failed to delete the group.
ERR_NOT_A_MEMBER	Indicates that the user is not a member of the group.
ERR_WRONG_GROUP_PASS	Indicates password mismatch for the password type group.
ERR_ALREADY_JOINED	Indicates that the user has already joined the group.
ERR_GROUP_NOT_JOINED	Indicates that the user is trying to access the group feature without joining it.
ERR_GROUP_JOIN_NOT_ALLOWED	Indicates that the user is trying to join the private group.
ERR_MEMBER_DELETE_FAILED	Indicates that the API has failed to remove a user from the group.
ERR_NO_VACANCY	Indicates that the group is full.
ERR_SAME_SCOPE	Indicates that the existing and new scope are same.
ERR_MEMBER_SCOPE_CHANGE_FAILED	Indicates that the has failed to change the scope.
ERR_NOT_A_BANNED_USER	Indicates that the API is trying to unban non-banned user.
ERR_BANNED_GROUPMEMBER	Indicates that the banned user is trying to access the group features.
ERR_ALREADY_BANNED	Indicates that the API is trying to ban an already banned user.
ERR_MEMBER_BAN_FAILED	Indicates that the API has failed to ban a user from the group.
ERR_MEMBER_UNBAN_FAILED	Indicates that the API has failed to unban a user for the group.
ERR_GROUP_NO_CLEARANCE	Indicates that the user does not have permission to perform the action in the group. For example, user with participant scope can not kick users with admin or moderator scope.
ERR_GROUP_NO_ADMIN_SCOPE	Indicates that the user does not have admin scope in the group.
ERR_GROUP_NO_MODERATOR_SCOPE	Indicates that the user does not have moderator scope in the group.
ERR_GROUP_NO_SCOPE_CLEARANCE	Indicates that the user does not have permission to change scope of other user.
ERR_GROUP_NO_SELF_ACTION	Indicates that the user is not allowed to perform action on himself. For example, changing his own scope.
Message Errors
ERR_EMPTY_RECEIVER	Indicates that the receiver cannot be empty.
ERR_INVALID_RECEIVER_TYPE	Indicates that the invalid receiver type.
ERR_CONVERSATION_NOT_FOUND	Indicates that the conversation id does not exists.
ERR_CONVERSATION_NOT_ACCESSIBLE	Indicates that the conversation id not accessible to the user. 1. A user can access his own one-to-one conversations. 2. A user can access the group conversations if he is member of the group.
ERR_USER_MESSAGE_DELETE_FAILED	Indicates that the API has failed to delete a one-to-one message.
ERR_MESSAGE_ID_NOT_FOUND	Indicates that the message does not exist.
ERR_INVALID_MESSAGE_DATA	Indicates invalid message body.
ERR_EMPTY_MESSAGE_TEXT	Indicates empty messages text for a text message.
ERR_INVALID_MESSAGE_TEXT	Indicates that the message text should be string.
ERR_EMPTY_MESSAGE_CATEGORY	Indicates message category cannot be empty.
ERR_INVALID_MESSAGE_CATEGORY	Indicates invalid message category.
ERR_EMPTY_MESSAGE_TYPE	Indicates message type cannot be empty.
ERR_INVALID_MESSAGE_TYPE	Indicates invalid message type.
ERR_EMPTY_MESSAGE_FILE	Indicates empty FILE for the media message.
ERR_MESSAGE_NOT_A_SENDER	Indicates that only sender can edit/delete the message.
ERR_MESSAGE_NO_ACCESS	Indicates user does not have access to the message. 1. For one-to-one message user should either be sender or receiver of the message. 2. For group message user should be the member of the group.
ERR_MESSAGE_ACTION_NOT_ALLOWED	Indicates that the message can not be edited or deleted. For example, Action messages cannot be edited or deleted by the API.
ERR_EMPTY_CUSTOM_DATA	Indicates data.customData can not be empty for custom message.
ERR_INVALID_MEDIA_MESSAGE	Indicates invalid media message.
ERR_INVALID_CUSTOM_DATA	Indicates invalid data.customData. The customData should be valid JSON.
ERR_INVALID_METADATA	Indicates invalid data.metadata. The metadata should be valid JSON.
ERR_WRONG_MESSAGE_THREAD	Indicates conversation mismatch for parent and a new threaded message.
ERR_MESSAGE_THREAD_NESTING	Indicates nested message threading.
ERR_WRONG_MESSAGE_THREAD_CATEGORY	Indicates conversation mismatch for parent and a new threaded message.
Calling Errors
ERR_CALLING_SELF	Indicates user is initiating call with himself.
ERR_CALL_BUSY_SELF	Indicates initiator of the call is participant of another ongoing call.
ERR_CALL_BUSY_GROUP	Indicates that for a group call, the group has and existing ongoing call.
ERR_CALL_BUSY_USER	Indicates that the recipient of the call is already busy on another call.
ERR_EMPTY_CALL_SESSION_ID	Indicates empty session id.
ERR_CALL_SESSION_NOT_FOUND	Indicates that the call does not exist.
ERR_CALL_TERMINATED	Indicates that a call is terminated. The error response is generated when a user tries to update the status of an ended call.
ERR_CALL_GROUP_ALREADY_JOINED	Indicates that the user is already a member of the group call.
ERR_CALL_GROUP_ALREADY_LEFT	Indicates that the user trying to leave the group call has already left the call.
ERR_CALL_INVALID_INIT	Indicates that call status cannot be updated to initiated.
ERR_CALL_USER_ALREADY_JOINED	Indicates that the one-to-one call was already joined by the recipient of the call.
ERR_CALL_GROUP_INVALID_STATUS	Indicates invalid call status for a group call. For example, group call cannot have a busy status.
ERR_CALL_ONGOING_TO_INVALID	Indicates updating invalid status for an ongoing call. For example, ongoing call can not become a busy call.
ERR_CALL_NOT_A_PART	Indicates that the user is not part of the call. For example, a third user tries to join a one-to-one call.
ERR_CALL_EMPTY_JOINED_AT	Indicates that the joinedAt body param is required to join a group.
ERR_CALL_NOT_STARTED	Indicates that status of call cannot be changed from initiated to ended directly.
Friends Errors
ERR_ALREADY_FRIEND	Indicates that the users are already friends.
ERR_NOT_A_FRIEND	Indicates unfriending non-friended users.
ERR_CANNOT_FORM_SELF_RELATION	Indicates user cannot friend himself.
ERR_FAILED_TO_ADD_FRIEND	Indicates that the API has failed to add friend.
Block Users Errors
ERR_CANNOT_BLOCK_SELF	Indicates that user cannot block himself.
ERR_BLOCKED_RECEIVER	Indicates user has blocked the receiver of the message/call.
ERR_BLOCKED_SENDER	Indicates that the iniator of the call is blocked by the recipient.
Extension Errors
ERR_EXTENSION_NOT_FOUND	Indicates extension does not exist.
ERR_BLOCKED_BY_EXTENSION	Indicates that the message is blocked by the extension. For example, human moderation extension can block the message sending.
Webhook Errors
ERR_WEBHOOK_NOT_FOUND	Indicates that the webhook does not exist.
ERR_BLOCKED_BY_WEBHOOK	Indicates that the message is blocked by the extension.
ERR_TRIGGER_NOT_FOUND	Indicates trigger does not exist.
General Errors
ERR_INVALID_API_VERSION	Indicates invalid API version.
ERR_API_NOT_FOUND	Indicates one from the list below: 1. API endpoint does not exist. 2. The endpoint does not use HTTP request method using which API is called.
ERR_MISSION_FAILED	Indicates one from the list below: 1. Fatal error. 2. Database Connection Timeout.
ERR_BAD_REQUEST	Indicates the failed validations for the body params.
ERR_OPERATION_FAILED	Indicates database operation failure.
ERR_EXCEPTION	Indicates incorrectly/poorly handled exception.
ERR_TOO_MANY_REQUESTS	Indicates rate limiting.
ERR_BAD_ERROR_RESPONSE	Indicates one from the list below: 1. The API developer has used unknown error code. 2. The API developer hasn’t reassigned the error code.
Websocket Errors
ERR_WS_INIT_FAILED	Indicates failure at Web Socket Server.
ERR_WS_APP_INIT_FAILED	Indicates App creation failure at Web Socket Server.
ERR_WS_APP_DESTROY_FAILED	Indicates App delete failure at Web Socket Server.
ERR_WS_ROLE_CREATION_FAILED	Indicates role creation failure at Web Socket Server.
ERR_WS_ROLE_DELETION_FAILED	Indicates role deletion failure at Web Socket Server.
ERR_WS_USER_CREATION_FAILED	Indicates user creation failure at Web Socket Server.
ERR_WS_USER_UPDATION_FAILED	Indicates user updation failure at Web Socket Server.
ERR_WS_GROUP_CREATION_FAILED	Indicates group creation failure at Web Socket Server.
ERR_WS_GROUP_DELETION_FAILED	Indicates group deletion failure at Web Socket Server.
ERR_WS_GROUP_JOIN_FAILED	Indicates group member join failure at Web Socket Server.