There will be errors when working with the API, and they must be correctly handled on the client.
An error is characterized by several parameters:
Numerical value similar to HTTP status. Contains information on the type of error that occurred: for example, a data input error, privacy error, or server error. This is a required parameter.
A string literal in the form of /[A-Z_0-9]+/, which summarizes the problem. For example, AUTH_KEY_UNREGISTERED. This is an optional parameter.
A full human-readable JSON list of RPC errors that can be returned by all methods in the API can be found here », what follows is a description of its fields:
errors - All error messages and codes for each method (object).descriptions - Descriptions for every error mentioned in errors (and a few other errors not related to a specific method)user_only - A list of methods that can only be used by users, not bots.bot_only - A list of methods that can only be used by bots, not users.Error messages and error descriptions may contain printf placeholders in key positions, for now only %d is used to map durations contained in error messages to error descriptions.
Example:
{
"errors": {
"420": {
"2FA_CONFIRM_WAIT_%d": [
"account.deleteAccount"
],
"SLOWMODE_WAIT_%d": [
"messages.forwardMessages",
"messages.sendInlineBotResult",
"messages.sendMedia",
"messages.sendMessage",
"messages.sendMultiMedia"
]
}
},
"descriptions": {
"2FA_CONFIRM_WAIT_%d": "Since this account is active and protected by a 2FA password, we will delete it in 1 week for security purposes. You can cancel this process at any time, you'll be able to reset your account in %d seconds.",
"SLOWMODE_WAIT_%d": "Slowmode is enabled in this chat: wait %d seconds before sending another message to this chat.",
"FLOOD_WAIT_%d": "Please wait %d seconds before repeating the action."
},
"user_only": [
"account.deleteAccount"
],
"bot_only": [
"messages.setInlineBotResults"
]
}There should be a way to handle errors that are returned in rpc_error constructors.
Below is a list of error codes and their meanings:
The request must be repeated, but directed to a different data center.
In all these cases, the error description's string literal contains the number of the data center (instead of the X) to which the repeated query must be sent. More information about redirects between data centers »
The query contains errors. In the event that a request was created using a form and contains user generated data, the user should be notified that the data must be corrected before the query is repeated.
There was an unauthorized attempt to use functionality available only to authorized users.
Privacy violation. For example, an attempt to write a message to someone who has blacklisted the current user.
An attempt to invoke a non-existent object, such as a method.
Similar to 400 BAD_REQUEST, but the app must display the error to the user a bit differently.
Do not display any visible error to the user when receiving the rpc_error constructor: instead, wait for an updateServiceNotification update, and handle it as usual.
Basically, an updateServiceNotification popup update will be emitted independently (ie NOT as an Updates constructor inside rpc_result but as a normal update) immediately after emission of a 406 rpc_error: the update will contain the actual localized error message to show to the user with a UI popup.
An exception to this is the AUTH_KEY_DUPLICATED error, which is only emitted if any of the non-media DC detects that an authorized session is sending requests in parallel from two separate TCP connections, from the same or different IP addresses.
Note that parallel connections are still allowed and actually recommended for media DCs.
Also note that by session we mean a logged-in session identified by an authorization constructor, fetchable using account.getAuthorizations, not an MTProto session.
If the client receives an AUTH_KEY_DUPLICATED error, the session was already invalidated by the server and the user must generate a new auth key and login again.
The maximum allowed number of attempts to invoke the given method with the given input parameters has been exceeded. For example, in an attempt to request a large number of text messages (SMS) for the same phone number.
An internal server error occurred while a request was being processed; for example, there was a disruption while accessing a database or file storage.
If a client receives a 500 error, or you believe this error should not have occurred, please collect as much information as possible about the query and error and send it to the developers.
If a server returns an error with a code other than the ones listed above, it may be considered the same as a 500 error and treated as an internal server error.