# HTTP status codes (/en/api-reference/api-ref/im/http-status-codes) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). This page describes the frequently returned HTTP status codes for the Chat RESTful API. ## `200` - Success [#200---success] The API request succeeds. ## `4xx` - Client error [#4xx---client-error] The API request fails due to a client error. Troubleshoot based on the returned `error` code and retry the request. ### 400 Bad Request [#400-bad-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](/en/api-reference/api-ref/im/user-system-registration#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](/en/api-reference/api-ref/im/message-management#retrieve-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](mailto\: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 is invalid when creating a group. | [Create a group](/en/api-reference/api-ref/im/chat-group-management/create-delete-retrieve-groups#creating-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](/en/api-reference/api-ref/im/user-system-registration#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. | ### 401 Unauthorized [#401-unauthorized] 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](/en/api-reference/api-ref/im/user-system-registration#registering-a-user) or [Registering multiple users](/en/api-reference/api-ref/im/user-system-registration#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. | ### 403 Forbidden [#403-forbidden] 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. | 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. | 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. | 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 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 groups 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 groups 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. | ### 404 Not Found [#404-not-found] 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 `app_id` 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](https://agora-ticket.agora.io/) 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](mailto\:support@agora.io). | ### 405 Method Not Allowed [#405-method-not-allowed] 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`. ### 408 Request Timeout [#408-request-timeout] Indicates that the server did not receive the API request within the allotted time. **Fix:** Resend the request. ### 413 Payload Too Large [#413-payload-too-large] 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](/en/api-reference/api-ref/im/message-management#upload-a-file) exceeds the allowed limit. | For more information about the size limit of message attachments, see [Message Length](./limitations#message-length). | ### 415 Unsupported Media Type [#415-unsupported-media-type] 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. | ### 429 Too Many Requests [#429-too-many-requests] 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](/en/realtime-media/im/reference/pricing). To upgrade your pricing plan, contact [support@agora.io](mailto\: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](/en/api-reference/api-ref/im#features). To upgrade your pricing plan, contact [support@agora.io](mailto\:support@agora.io). | ## `5xx` - Server error [#5xx---server-error] 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](https://agoraio.zendesk.com/hc/en-us) to Agora Support and provide your system logs. If you encounter a 5xx error, [contact Agora technical support](https://agoraio.zendesk.com/hc/en-us). ### 500 Internal Server Error [#500-internal-server-error] 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. | ### 501 Not Implemented [#501-not-implemented] The server cannot recognize or implement the API request. ### 502 Bad Gateway [#502-bad-gateway] The server, while acting as a gateway or proxy, received an invalid response from the upstream server. ### 503 Service Unavailable [#503-service-unavailable] The server is unavailable to handle the request. ### 504 Gateway Timeout [#504-gateway-timeout] The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server.