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 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 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 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. |
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 scenarios:
|
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. |
501 Not Implemented
This status code indicates that the server cannot recognize and implement the API request.
502 Bad Gateway
This status code indicates that the server, while acting as a gateway or proxy, receives an invalid response from the upstream server.
503 Service Unavailable
This status code indicates that the server is unavailable to handle the request.
504 Gateway Timeout
This status code indicates that the server, when acting as a gateway or proxy, does not get a timely response from the upstream server.