HTTP status codes

This page describes the HTTP status codes that are frequently returned when using the Chat RESTful API.

`200` - Success

This HTTP status code indicates that the API request succeeds.

`4xx` - Client error

These HTTP status codes indicate that the API request fails due to a client error. You can troubleshoot based on the returned error code and retry the request.

400 Bad Request

This status code indicates that the API request could not be understood by the server due to malformed syntax.

Status code	Error code	Error message	Description
`400`	`invalid_grant`	"Invalid username or password."	The error message returned because the specified username or password is invalid.
`400`	`json_parse`	"Unexpected character."	The error message returned because the request body does not conform to the standard JSON format, as a consequence the server cannot parse it properly.
`400`	`illegal_argument`	"Entity 'user' requires a property named username."	The error message returned because the username is not specified when registering users.
`400`	`illegal_argument`	"Password or pin must provided."	The error message returned because the password is not specified when registering users.
`400`	`illegal_argument`	"New password is required. Old password is required."	The error message returned because the new password or old password is not provided when changing passwords.
`400`	`illegal_argument`	"This is an invalid request."	The error message returned because the request URL, the request header, or the request body is invalid.
`400`	`illegal_argument`	"'From' can't be empty."	The error message returned because the sender is not specified when sending messages.
`400`	`illegal_argument`	"'Target_type' can only be 'users' or 'chatgroups' or 'chatrooms'."	The error message returned because the values other than `users`, `chatgroups`, or `chatrooms` is passed to `target_type` when sending messages
`400`	`illegal_argument`	"`{username}` is not legal."	The error message returned because the specified username is invalid when registering users. For details, see Registering a user.
`400`	`illegal_argument`	“message is too large”	The error message returned because the body of the message to be sent exceeds 40 KB.
`400`	`illegal_argument`	"This 'chatmessage' request is not supported."	The error message returned because the specified time format is incorrect when querying chat history. The correct time format is YYYYMMDDHH.
`400`	`illegal_argument`	"Illegal arguments: appkey: `{app_key}`, time: `{yyyymmddhh}`, maybe chat message history is expired or unstored."	The error message returned because the chat history within the queried time period has expired or has not been generated. For details, see Retrieving historical messages.
`400`	`invalid_parameter`	"Some of `{group_id}` are not valid fields."	The error message returned because the specified name, description, or size of the group chat is invalid when creating group chats.
`400`	`required_property_not_found`	"Entity user requires a property named 'username'."	The error message returned because the username is not provided when changing passwords.
`400`	`duplicate_unique_property_exists`	"Application null Entity user requires that property named 'username' be unique, value of `{username}` exists."	The error message returned because the specified username already exists when registering users.
`400`	N/A	"set presence failed"	The error message returned because the request to set the presence status fails.
`400`	N/A	"ext is too big"	The error message returned because the length of the custom presence status exceeds the limit.
`400`	N/A	"resource not exist"	The error message returned because the device resource does not exist.
`400`	N/A	"you can't sub yourself"	The error message returned because you are not allowed to subscribe to your own presence status.
`400`	N/A	"too many sub presence"	The error message returned because the number of subscriptions exceeds the limit.
`400`	N/A	"too many get presences"	The error message returned because the number of users whose presence statuses you are attempting to retrieve exceeds the limit.
`400`	N/A	"too many unsub presences"	The error message returned because the number of users from whom you are attempting to unsubscribe exceeds the limit.
`400`	N/A	"too many queries"	The error message returned because the call frequency exceeds the limit.

401 Unauthorized

This status code indicates that the authentication process could not be implemented due to invalid tokens.

Status code	Error code	Error message	Description
`401`	`unauthorized`	"Registration is not open, please contact the app admin."	The error message returned because you pass in an incorrect app token or do not pass in an app token when you call the API of registering a user or registering multiple users. For example, you pass in an app token that has already expired or is in incorrect format.
`401`	`unauthorized`	"Unable to authenticate due to expired access token."	This error message is returned because you pass in an expired app token or do not pass in an app token when you call any other RESTful API than the API of registering a user or registering multiple users.
`401`	`auth_bad_access_token`	"Unable to authenticate due to corrupt access token."	The error message returned because you pass in an app token that is in invalid format when you call any other RESTful API than the API of registering a user or registering multiple users.
`401`	`auth_bad_access_token`	"Unable to authenticate."	The error message returned because the server cannot recognize your app token that is in the correct format, but is not generated by the server that receives the request. This error occurs when you call any other RESTful API than the API of registering a user or registering multiple users.

403 Forbidden

This status code indicates that the API request is rejected by the server due to forbidden operations.

Status code	Error code	Error message	Description
`403`	`forbidden_op`	"Can not join this group, reason: user: `{username}` already in group: `{group_id}`."	The error message returned because the user being added is already in the group chat.
`403`	`forbidden_op`	"Users `{username}` are not members of this group!"	The error message returned because the user being removed does not exist in the group chat.
`403`	`forbidden_op`	"User: `{username}` doesn't exist in group: `{group_id}`."	The error message returned because the user being granted the ownership does not exist in the group chat.
`403`	`forbidden_op`	"New owner and old owner are the same."	The error message returned because the specified user being granted the ownership is already the group chat owner.
`403`	`forbidden_op`	"Forbidden operation on group owner!"	The error message returned because the specified operation cannot be performed on group chat owners, such as adding the group chat owner to block list.
`403`	`forbidden_op`	"Can not join this group, reason：user: `{username}` has joined too many groups/chatroom!"	The error message returned because the number of group chats or chat rooms joined by a user has reached the limit.
`403`	`forbidden_op`	"This appKey has create too many groups/chatrooms!"	The number of group chats or chat rooms created by using an App key has reached the limit. For details, see Pricing plans.
`403`	`exceed_limit`	"Invitee's contact max count"	The user receiving the friend request has reached the maximum number of contacts allowed.
`403`	`exceed_limit`	"Inviter's contact max count"	The user sending the friend request has reached the maximum number of contacts allowed.

404 Not Found

This status code indicates that the specified resources of the API request could not be found by the server.

Status code	Error code	Error message	Description
`404`	`organization_application_not_found`	"Could not find application for `{org_url}` from URI: `{app_url}`/token."	The error message returned because the specified organization or application does not exist.
`404`	`service_resource_not_found`	"Service resource not found."	The error message returned in one of the following use-cases: The specified user does not exist when you call APIs related to the user system. The specified group does not exist when you call group-related APIs. The specified chat room does not exist when you call APIs related to the chat room.
`404`	`resource_not_found`	"username XXXX doesn't exist"	The specified user does not exist. For example, the user that you invite to join the group during group creation does not exist.
`404`	`service_resource_not_found`	"Service resource not found."	The error message returned because either the specified user being queried or removed does not exist, or dirty data blocks the proper read operation. To address the dirty read problem, you can pass in the UUID to delete the existing user and register with the same username again.
`404`	`storage_object_not_found`	"Failed to find chat message history download url for appkey: `{app_key}`, time: `{yyyymmddhh}`."	The error message returned because no chat history exists within the queried time period. To double check, submit a ticket to Agora Support.
`404`	`file_expired`	`file xxxxx is expired`	The file has expired.

405 Method Not Allowed

This status code indicates that the method of the API request is not supported by the server.

408 Request Timeout

This status code indicates that the server does not receive the API request within the alloted time period.

413 Payload Too Large

This status code indicates that the API request is larger than the server can process.

Status code	Error code	Error message	Description
`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 upper limit.

415 Unsupported Media Type

This status code indicates that the format of the API request is not supported by the server.

Status code	Error code	Error message	Description
`415`	`web_application`	"Unsupported Media Type."	The error message returned because the format of the client request is not supported by the server. For example, the request header includes extra parameters, the request header does not include `"Content-Type":"application/json"`, or the request body does not conform to the standard JSON format.

429 Too Many Requests

This status code indicates that the API request surpasses the call limit.

Status code	Error code	Error message	Description
`429`	`resource_limited`	"You have exceeded the limit of the `{pricing_plan}` edition. Please upgrade to higher edition."	The error message returned because the usage of Chat exceeds the limit of the current pricing plan. For details, see Pricing. To upgrade the pricing plan, contact support@agora.io.
`429`	`reach_limit`	"This request has reached api limit."	The error message returned because the calling frequency of the Chat API surpasses the call limit. For details, see Limitations. To upgrade the pricing plan, contact support@agora.io.

`5xx` - Server error

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

500 Internal Server Error

This status code indicates that the server encounters 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 error message returned because the `contains` operand cannot be used on the `username` property as this property does not support full-text indexing.
`500`	`unsupported_service_operation`	"Service operation not supported."	The error message returned because the request URL does not support the request method.
`500`	`web_application`	"javax.ws.rs.WebApplicationException"	The error message returned because the request URL is invalid.