HTTP status codes

This page describes the frequently returned HTTP status codes for the Chat RESTful API.

The API request succeeds.

The API request fails due to a client error. Troubleshoot based on the returned error code and retry the request.

Indicates that the API request could not be understood by the server because of malformed syntax.

Status code	Error code	Error message	Description	Fix
400	json_parse	"Unexpected character."	The request body does not conform to the standard JSON format, so the server cannot parse it properly.	Use tools to check and ensure that the JSON format is correct.
400	illegal_argument	"Entity 'user' requires a property named username."	The username is not specified when registering a user.	Pass the username parameter when registering a user.
400	illegal_argument	"This is an invalid request."	The request URL, header, or body is invalid.	Check that the request URL, header, and body are correct.
400	illegal_argument	"'From' can't be empty."	The sender is not specified when sending a message.	When sending a message, pass the from field.
400	illegal_argument	"'Target_type' can only be 'users', 'chatgroups', or 'chatrooms'."	A value other than users, chatgroups, or chatrooms is passed to target_type when sending a message.	The target_type parameter must be users, chatgroups, or chatrooms.
400	illegal_argument	"{username} is not legal."	The specified username is invalid when registering a user. For details, see Registering a user.	When registering a user, pass a valid user ID username.
400	illegal_argument	"message is too large"	The body or extension information of the message exceeds the allowed size.	Limit the content of the body and ext fields to no more than 5 KB.
400	illegal_argument	"This chatmessage request is not supported."	The specified time format is incorrect when querying chat history. The correct format is yyyyMMddHH.	Format the time parameter as yyyyMMddHH.
400	illegal_argument	"Illegal arguments: appkey: {app_key}, time: {yyyymmddhh}, maybe chat message history is expired or unstored."	The chat history for the queried time period has expired or has not been generated. For details, see Retrieving historical messages.	When retrieving chat history, note the following restrictions: A single request retrieves message history for one hour starting from the specified time. You can retrieve historical messages for up to the past 3 days. To extend this limit, contact support@agora.io. When platform message volume is high, generating historical records may take time. For time-sensitive requirements, pull records after 24 hours.
400	invalid_parameter	"Some of {group_id} are not valid fields."	The specified name, description, or size of the group chat is invalid when creating a group chat.	Create a group. Enter a valid group name, description, and maximum number of members.
400	duplicate_unique _property_exists	"Application null Entity user requires that property named username be unique, value of {username} exists."	The specified username already exists when registering a user.	User IDs must be unique within the app. When registering a user, pass a unique user ID.
400	N/A	"set presence failed"	The request to set the presence status failed.	Reset the user's presence status and ensure that the correct parameters are passed.
400	N/A	"ext is too big"	The custom presence status exceeds the allowed length.	Limit the online status extension message to no more than 1024 bytes.
400	N/A	"resource not exist"	The specified device resource does not exist.	Pass the correct device resource ID. The ID is a unique identifier assigned by the server in the format {device type}_{resource ID}, where device type can be android, ios, or web, and resource ID is assigned by the SDK. For example, android_123423453246.
400	N/A	"you can't sub yourself"	Subscribing to your own presence status is not allowed.	Remove yourself from the list of users you subscribe to.
400	N/A	"too many sub presence"	The number of presence subscriptions exceeds the limit.	You can subscribe to the presence status of up to 100 user IDs at a time.
400	N/A	"too many get presences"	The number of presence statuses you are trying to retrieve exceeds the limit.	You can retrieve the presence status of up to 100 user IDs at a time.
400	N/A	"too many unsub presences"	The number of users you are trying to unsubscribe from exceeds the limit.	You can unsubscribe from the presence status of up to 100 user IDs at a time.
400	N/A	"too many queries"	The call frequency exceeds the limit.	Reduce the frequency of your API calls.

Indicates that the authentication process could not be implemented due to invalid tokens.

Status code	Error code	Error message	Description	Fix
401	unauthorized	"Registration is not open, please contact the app admin."	The app token is missing, incorrect, expired, or in an invalid format when calling Registering a user or Registering multiple users.	Pass a valid app token.
401	unauthorized	"Unable to authenticate due to expired access token."	The app token is missing or expired when calling any RESTful API other than the user registration APIs.	Pass a valid app token.
401	auth_bad_access_token	"Unable to authenticate due to corrupt access token."	The app token is in an invalid format when calling any RESTful API other than the user registration APIs.	Pass a valid app token.
401	auth_bad_access_token	"Unable to authenticate."	The app token format is correct but was not generated by the server that receives the request. This happens when calling any RESTful API other than the user registration APIs.	Pass a valid app token generated by the Agora server.

Indicates that the API request is rejected by the server due to forbidden operations.

Status code	Error code	Error message	Description	Fix
403	forbidden_op	"Can not join this group, reason: user: {username} already in group: {group_id}."	The user is already a member of the group chat.	Do not add duplicate users to the group.
403	forbidden_op	"Users {username} are not members of this group!"	The user to be removed is not a member of the group chat.	Only remove users who are members of the group.
403	forbidden_op	"User: {username} doesn't exist in group: {group_id}."	The user to be assigned ownership is not a member of the group chat.	Transfer ownership only to members within the group.
403	forbidden_op	"New owner and old owner are the same."	The new owner is the same as the current owner.	Transfer ownership to a different member.
403	forbidden_op	"Forbidden operation on group owner!"	The operation is not allowed on the group chat owner, such as blocking the owner.	Do not perform restricted actions on the group owner.
403	forbidden_op	"Can not join this group, reason：user: {username} has joined too many groups/chatroom!"	The user has joined the maximum number of group chats or chat rooms.	Users cannot join more than the allowed number of groups or chat rooms.
403	forbidden_op	"This appKey has created too many groups/chatrooms!"	The App Key has reached the limit for creating group chats or chat rooms.	Users cannot create more than the allowed number of groups or chat rooms.
403	exceed_limit	"Invitee's contact max count"	The user receiving the friend request has reached the maximum number of contacts.	The maximum number of contacts for a user has been reached.
403	exceed_limit	"Inviter's contact max count"	The user sending the friend request has reached the maximum number of contacts.	The maximum number of contacts for a user has been reached.

Indicates that the specified resources of the API request could not be found by the server.

Status code	Error code	Error message	Description	Fix
404	organization_application_not_found	"Could not find application for {org_url} from URI: {app_url}/token."	The specified organization or application does not exist.	Pass the correct org_name and app_name when calling the RESTful API.
404	service_resource_not_found	"Service resource not found."	The specified user, group, or chat room does not exist when calling user-, group-, or chat room–related APIs.	Pass the correct User ID, Group ID, or Chat Room ID when calling the RESTful API.
404	resource_not_found	"username XXXX doesn't exist"	The specified user does not exist. For example, the invited user during group creation does not exist.	Pass the correct User ID when calling the RESTful API.
404	service_resource_not_found	"Service resource not found."	The specified user does not exist, or dirty data blocks the operation. Delete the user by UUID and re-register the same username.	Pass the UUID to delete the user, then register the username again.
404	storage_object_not_found	"Failed to find chat message history download URL for appkey: {app_key}, time: {yyyymmddhh}."	No chat history exists within the queried time period.	Submit a ticket to Agora Support.
404	file_expired	"file xxxxx is expired"	The file has expired.	By default, message attachments are stored for 7 days. To extend storage, contact support@agora.io.

Indicates that the API request method is not supported by the server.

Fix: Follow the RESTful API documentation and use the correct request methods: GET, POST, PUT, and DELETE.

Indicates that the server did not receive the API request within the allotted time.

Fix: Resend the request.

Indicates that the API request is larger than the maximum server can process.

Status code	Error code	Error message	Description	Fix
413	file exceeding maximum limit	"the file size exceeds the maximum limit."	The size of the message attachment uploaded using the message upload API exceeds the allowed limit.	For more information about the size limit of message attachments, see Message Length.

Indicates that the format of the API request is not supported by the server.

Status code	Error code	Error message	Description	Fix
415	web_application	"Unsupported Media Type."	The format of the client request is not supported by the server. For example, the request header includes extra parameters, does not include "Content-Type": "application/json", or the request body does not conform to the standard JSON format.	Ensure that the request format meets the server’s requirements. For example, include "Content-Type": "application/json" in the request header and ensure that the request body uses the standard JSON format.

Indicates that the API request exceeds the allowed call limit.

Status code	Error code	Error message	Description	Fix
429	resource_limited	"You have exceeded the limit of the {pricing_plan} edition. Please upgrade to higher edition."	The usage of Chat exceeds the limit of the current pricing plan.	For usage limits, see Pricing. To upgrade your pricing plan, contact support@agora.io.
429	reach_limit	"This request has reached API limit."	The calling frequency of the Chat API exceeds the allowed limit.	You cannot exceed the call frequency limit for RESTful APIs. For details, see RESTful API Call Frequency Limit. To upgrade your pricing plan, contact support@agora.io.

These HTTP status codes indicate that the API request failed due to a server error. If the request continues to fail after retries, submit a ticket to Agora Support and provide your system logs.

info

If you encounter a 5xx error, contact Agora technical support.

Indicates that the server encountered an unexpected condition that prevents it from fulfilling the request.

Status code	Error code	Error message	Description
500	no_full_text_index	"Entity 'user' with property named 'username' is not full text indexed. You cannot use the 'contains' operand on this field."	The contains operand cannot be used on the username property because it does not support full-text indexing.
500	unsupported_service_operation	"Service operation not supported."	The request method is not supported by the request URL.
500	web_application	"javax.ws.rs.WebApplicationException"	The request URL is invalid.

The server cannot recognize or implement the API request.

The server, while acting as a gateway or proxy, received an invalid response from the upstream server.

The server is unavailable to handle the request.

The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server.