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`	"Group member `{username}` doesn’t exist."	The error message returned because the specified username does not exist when adding users to a chat group.
`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 chat group is invalid when creating chat groups.
`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 the app token is not included in the request header when registering users.
`401`	`unauthorized`	"Unable to authenticate due to expired access token."	The error message returned because the token has expired.
`401`	`auth_bad_access_token`	"Unable to authenticate due to corrupt access token."	The error message returned because the token format is invalid.
`401`	`auth_bad_access_token`	"Unable to authenticate."	The error message returned because the token is not generated by the server that receives the request, and as a consequence the server cannot recognize the token.

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 chat group.
`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 chat group.
`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 chat group.
`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 chat group owner.
`403`	`forbidden_op`	"Forbidden operation on group owner!"	The error message returned because the specified operation cannot be performed on chat group owners, such as adding the chat group 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 chat groups 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 chat groups or chat rooms created by using an App key has reached the limit. For details, see Pricing plans.

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 because the specified user, chat group, or chat room 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.

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`	`Request Entity Too Large`	"Request Entity Too Large."	The error message returned because the size of the client request exceeds the maximum size limit of the server. For example, the message body exceeds 5 KB or the uploaded files exceed 10 MB.

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.