mirror of
https://github.com/MarshalX/telegram-crawler.git
synced 2024-12-11 17:31:02 +01:00
246 lines
16 KiB
HTML
246 lines
16 KiB
HTML
<!DOCTYPE html>
|
||
<html class="">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<title>Error handling </title>
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta property="description" content="How to handle API return errors correctly.">
|
||
<meta property="og:title" content="Error handling ">
|
||
<meta property="og:image" content="80b44334eec2aec564">
|
||
<meta property="og:description" content="How to handle API return errors correctly.">
|
||
<link rel="icon" type="image/svg+xml" href="/img/website_icon.svg?4">
|
||
<link rel="apple-touch-icon" sizes="180x180" href="/img/apple-touch-icon.png">
|
||
<link rel="icon" type="image/png" sizes="32x32" href="/img/favicon-32x32.png">
|
||
<link rel="icon" type="image/png" sizes="16x16" href="/img/favicon-16x16.png">
|
||
<link rel="alternate icon" href="/img/favicon.ico" type="image/x-icon" />
|
||
<link href="/css/bootstrap.min.css?3" rel="stylesheet">
|
||
|
||
<link href="/css/telegram.css?241" rel="stylesheet" media="screen">
|
||
<style>
|
||
</style>
|
||
</head>
|
||
<body class="preload">
|
||
<div class="dev_page_wrap">
|
||
<div class="dev_page_head navbar navbar-static-top navbar-tg">
|
||
<div class="navbar-inner">
|
||
<div class="container clearfix">
|
||
<ul class="nav navbar-nav navbar-right hidden-xs"><li class="navbar-twitter"><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)"><i class="icon icon-twitter"></i><span> Twitter</span></a></li></ul>
|
||
<ul class="nav navbar-nav">
|
||
<li><a href="//telegram.org/">Home</a></li>
|
||
<li class="hidden-xs"><a href="//telegram.org/faq">FAQ</a></li>
|
||
<li class="hidden-xs"><a href="//telegram.org/apps">Apps</a></li>
|
||
<li class="active"><a href="/api">API</a></li>
|
||
<li class=""><a href="/mtproto">Protocol</a></li>
|
||
<li class=""><a href="/schema">Schema</a></li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="container clearfix">
|
||
<div class="dev_page">
|
||
<div id="dev_page_content_wrap" class=" ">
|
||
<div class="dev_page_bread_crumbs"><ul class="breadcrumb clearfix"><li><a href="/api" >API</a></li><i class="icon icon-breadcrumb-divider"></i><li><a href="/api/errors" >Error handling </a></li></ul></div>
|
||
<h1 id="dev_page_title">Error handling </h1>
|
||
|
||
<div id="dev_page_content"><p>There will be errors when working with the API, and they must be correctly handled on the client.<br>
|
||
An error is characterized by several parameters:</p>
|
||
<h4><a class="anchor" href="#error-code" id="error-code" name="error-code"><i class="anchor-icon"></i></a>Error Code</h4>
|
||
<p>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.</p>
|
||
<h4><a class="anchor" href="#error-type" id="error-type" name="error-type"><i class="anchor-icon"></i></a>Error Type</h4>
|
||
<p>A string literal in the form of <code>/[A-Z_0-9]+/</code>, which summarizes the problem. For example, <code>AUTH_KEY_UNREGISTERED</code>. This is an optional parameter.</p>
|
||
<h4><a class="anchor" href="#error-database" id="error-database" name="error-database"><i class="anchor-icon"></i></a>Error Database</h4>
|
||
<p>A full human-readable JSON list of RPC errors that can be returned by all methods in the API can be found <a href="/file/400780400741/4/8hsnYXGWGeI.133746.json/837006fc367dabeebe">here »</a>, what follows is a description of its fields: </p>
|
||
<ul>
|
||
<li><code>errors</code> - All error messages and codes for each method (object).<ul>
|
||
<li>Keys: Error codes as strings (numeric strings)</li>
|
||
<li>Values: All error messages for each method (object)<ul>
|
||
<li>Keys: Error messages (string)</li>
|
||
<li>Values: An array of methods which may emit this error (array of strings, may be empty for errors that can be emitted by any method)</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><code>descriptions</code> - Descriptions for every error mentioned in <code>errors</code> (and a few other errors not related to a specific method)<ul>
|
||
<li>Keys: Error messages</li>
|
||
<li>Values: Error descriptions</li>
|
||
</ul>
|
||
</li>
|
||
<li><code>user_only</code> - A list of methods that can only be used by users, <strong>not</strong> bots.</li>
|
||
<li><code>bot_only</code> - A list of methods that can only be used by bots, <strong>not</strong> users.</li>
|
||
</ul>
|
||
<p>Error messages and error descriptions may contain <code>printf</code> placeholders in key positions, for now only <code>%d</code> is used to map durations contained in error messages to error descriptions.</p>
|
||
<p>Example:</p>
|
||
<pre><code class="language-json">{
|
||
"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"
|
||
]
|
||
}</code></pre>
|
||
<hr>
|
||
<h4><a class="anchor" href="#error-constructors" id="error-constructors" name="error-constructors"><i class="anchor-icon"></i></a>Error Constructors</h4>
|
||
<p>There should be a way to handle errors that are returned in <a href="/mtproto/service_messages#rpc-error">rpc_error</a> constructors.</p>
|
||
<p>Below is a list of error codes and their meanings:</p>
|
||
<h3><a class="anchor" href="#303-see-other" id="303-see-other" name="303-see-other"><i class="anchor-icon"></i></a>303 SEE_OTHER</h3>
|
||
<p>The request must be repeated, but directed to a different data center.</p>
|
||
<h4><a class="anchor" href="#examples-of-errors" id="examples-of-errors" name="examples-of-errors"><i class="anchor-icon"></i></a>Examples of Errors:</h4>
|
||
<ul>
|
||
<li>FILE_MIGRATE_X: the file to be accessed is currently stored in a different data center.</li>
|
||
<li>PHONE_MIGRATE_X: the phone number a user is trying to use for authorization is associated with a different data center.</li>
|
||
<li>NETWORK_MIGRATE_X: the source IP address is associated with a different data center (for registration)</li>
|
||
<li>USER_MIGRATE_X: the user whose identity is being used to execute queries is associated with a different data center (for registration)</li>
|
||
</ul>
|
||
<p>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.
|
||
<a href="/api/datacenter">More information about redirects between data centers »</a></p>
|
||
<h3><a class="anchor" href="#400-bad-request" id="400-bad-request" name="400-bad-request"><i class="anchor-icon"></i></a>400 BAD_REQUEST</h3>
|
||
<p>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.</p>
|
||
<h4><a class="anchor" href="#examples-of-errors" id="examples-of-errors" name="examples-of-errors"><i class="anchor-icon"></i></a>Examples of Errors:</h4>
|
||
<ul>
|
||
<li>FIRSTNAME_INVALID: The first name is invalid</li>
|
||
<li>LASTNAME_INVALID: The last name is invalid</li>
|
||
<li>PHONE_NUMBER_INVALID: The phone number is invalid</li>
|
||
<li>PHONE_CODE_HASH_EMPTY: phone_code_hash is missing</li>
|
||
<li>PHONE_CODE_EMPTY: phone_code is missing</li>
|
||
<li>PHONE_CODE_EXPIRED: The confirmation code has expired</li>
|
||
<li>API_ID_INVALID: The api_id/api_hash combination is invalid</li>
|
||
<li>PHONE_NUMBER_OCCUPIED: The phone number is already in use</li>
|
||
<li>PHONE_NUMBER_UNOCCUPIED: The phone number is not yet being used</li>
|
||
<li>USERS_TOO_FEW: Not enough users (to create a chat, for example)</li>
|
||
<li>USERS_TOO_MUCH: The maximum number of users has been exceeded (to create a chat, for example)</li>
|
||
<li>TYPE_CONSTRUCTOR_INVALID: The type constructor is invalid</li>
|
||
<li>FILE_PART_INVALID: The file part number is invalid</li>
|
||
<li>FILE_PARTS_INVALID: The number of file parts is invalid</li>
|
||
<li>FILE_PART_X_MISSING: Part X (where X is a number) of the file is missing from storage</li>
|
||
<li>MD5_CHECKSUM_INVALID: The MD5 checksums do not match</li>
|
||
<li>PHOTO_INVALID_DIMENSIONS: The photo dimensions are invalid</li>
|
||
<li>FIELD_NAME_INVALID: The field with the name FIELD_NAME is invalid</li>
|
||
<li>FIELD_NAME_EMPTY: The field with the name FIELD_NAME is missing</li>
|
||
</ul>
|
||
<h3><a class="anchor" href="#401-unauthorized" id="401-unauthorized" name="401-unauthorized"><i class="anchor-icon"></i></a>401 UNAUTHORIZED</h3>
|
||
<p>There was an unauthorized attempt to use functionality available only to authorized users.</p>
|
||
<h4><a class="anchor" href="#examples-of-errors" id="examples-of-errors" name="examples-of-errors"><i class="anchor-icon"></i></a>Examples of Errors:</h4>
|
||
<ul>
|
||
<li>AUTH_KEY_UNREGISTERED: The key is not registered in the system</li>
|
||
<li>AUTH_KEY_INVALID: The key is invalid</li>
|
||
<li>USER_DEACTIVATED: The user has been deleted/deactivated</li>
|
||
<li>SESSION_REVOKED: The authorization has been invalidated, because of the user terminating all sessions</li>
|
||
<li>SESSION_EXPIRED: The authorization has expired</li>
|
||
<li>AUTH_KEY_PERM_EMPTY: The method is unavailable for temporary authorization key, not bound to permanent</li>
|
||
</ul>
|
||
<h3><a class="anchor" href="#403-forbidden" id="403-forbidden" name="403-forbidden"><i class="anchor-icon"></i></a>403 FORBIDDEN</h3>
|
||
<p>Privacy violation. For example, an attempt to write a message to someone who has blacklisted the current user.</p>
|
||
<h3><a class="anchor" href="#404-not-found" id="404-not-found" name="404-not-found"><i class="anchor-icon"></i></a>404 NOT_FOUND</h3>
|
||
<p>An attempt to invoke a non-existent object, such as a method.</p>
|
||
<h3><a class="anchor" href="#406-not-acceptable" id="406-not-acceptable" name="406-not-acceptable"><i class="anchor-icon"></i></a>406 NOT_ACCEPTABLE</h3>
|
||
<p>Similar to <a href="#400-bad-request">400 BAD_REQUEST</a>, but the app must display the error to the user a bit differently.<br>
|
||
Do not display any visible error to the user when receiving the <code>rpc_error</code> constructor: instead, wait for an <a href="/constructor/updateServiceNotification">updateServiceNotification</a> update, and handle it as usual.<br>
|
||
Basically, an <a href="/constructor/updateServiceNotification">updateServiceNotification</a> <code>popup</code> update will be emitted independently (ie NOT as an <a href="/type/Updates">Updates</a> constructor inside <code>rpc_result</code> but as a normal update) immediately after emission of a 406 <code>rpc_error</code>: the update will contain the actual localized error message to show to the user with a UI popup. </p>
|
||
<p>An exception to this is the <code>AUTH_KEY_DUPLICATED</code> 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.<br>
|
||
Note that parallel connections are still allowed and actually recommended for media DCs.<br>
|
||
Also note that by session we mean a logged-in session identified by an <a href="/constructor/authorization">authorization</a> constructor, fetchable using <a href="/method/account.getAuthorizations">account.getAuthorizations</a>, not an MTProto session. </p>
|
||
<p>If the client receives an <code>AUTH_KEY_DUPLICATED</code> error, the session was already invalidated by the server and the user must generate a new auth key and login again. </p>
|
||
<h3><a class="anchor" href="#420-flood" id="420-flood" name="420-flood"><i class="anchor-icon"></i></a>420 FLOOD</h3>
|
||
<p>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.</p>
|
||
<h4><a class="anchor" href="#error-example" id="error-example" name="error-example"><i class="anchor-icon"></i></a>Error Example:</h4>
|
||
<ul>
|
||
<li>FLOOD_WAIT_X: A wait of X seconds is required (where X is a number)</li>
|
||
<li>FLOOD_PREMIUM_WAIT_X: A wait of X seconds is required (where X is a number); the user may also purchase a <a href="/api/premium">Telegram Premium subscription</a> to remove this limitation. See <a href="/api/files">here »</a> for more info on how to handle this error. </li>
|
||
</ul>
|
||
<h3><a class="anchor" href="#500-internal" id="500-internal" name="500-internal"><i class="anchor-icon"></i></a>500 INTERNAL</h3>
|
||
<p>An internal server error occurred while a request was being processed; for example, there was a disruption while accessing a database or file storage.</p>
|
||
<p>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.</p>
|
||
<h3><a class="anchor" href="#other-error-codes" id="other-error-codes" name="other-error-codes"><i class="anchor-icon"></i></a>Other Error Codes</h3>
|
||
<p>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 <a href="#500-internal">internal server error</a>.</p></div>
|
||
|
||
</div>
|
||
|
||
</div>
|
||
</div>
|
||
<div class="footer_wrap">
|
||
<div class="footer_columns_wrap footer_desktop">
|
||
<div class="footer_column footer_column_telegram">
|
||
<h5>Telegram</h5>
|
||
<div class="footer_telegram_description"></div>
|
||
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
|
||
</div>
|
||
|
||
<div class="footer_column">
|
||
<h5><a href="//telegram.org/faq">About</a></h5>
|
||
<ul>
|
||
<li><a href="//telegram.org/faq">FAQ</a></li>
|
||
<li><a href="//telegram.org/privacy">Privacy</a></li>
|
||
<li><a href="//telegram.org/press">Press</a></li>
|
||
</ul>
|
||
</div>
|
||
<div class="footer_column">
|
||
<h5><a href="//telegram.org/apps#mobile-apps">Mobile Apps</a></h5>
|
||
<ul>
|
||
<li><a href="//telegram.org/dl/ios">iPhone/iPad</a></li>
|
||
<li><a href="//telegram.org/android">Android</a></li>
|
||
<li><a href="//telegram.org/dl/web">Mobile Web</a></li>
|
||
</ul>
|
||
</div>
|
||
<div class="footer_column">
|
||
<h5><a href="//telegram.org/apps#desktop-apps">Desktop Apps</a></h5>
|
||
<ul>
|
||
<li><a href="//desktop.telegram.org/">PC/Mac/Linux</a></li>
|
||
<li><a href="//macos.telegram.org/">macOS</a></li>
|
||
<li><a href="//telegram.org/dl/web">Web-browser</a></li>
|
||
</ul>
|
||
</div>
|
||
<div class="footer_column footer_column_platform">
|
||
<h5><a href="/">Platform</a></h5>
|
||
<ul>
|
||
<li><a href="/api">API</a></li>
|
||
<li><a href="//translations.telegram.org/">Translations</a></li>
|
||
<li><a href="//instantview.telegram.org/">Instant View</a></li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div class="footer_columns_wrap footer_mobile">
|
||
<div class="footer_column">
|
||
<h5><a href="//telegram.org/faq">About</a></h5>
|
||
</div>
|
||
<div class="footer_column">
|
||
<h5><a href="//telegram.org/blog">Blog</a></h5>
|
||
</div>
|
||
<div class="footer_column">
|
||
<h5><a href="//telegram.org/apps">Apps</a></h5>
|
||
</div>
|
||
<div class="footer_column">
|
||
<h5><a href="/">Platform</a></h5>
|
||
</div>
|
||
<div class="footer_column">
|
||
<h5><a href="//telegram.org/press">Press</a></h5>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<script src="/js/main.js?47"></script>
|
||
|
||
<script>backToTopInit("Go up");
|
||
removePreloadInit();
|
||
</script>
|
||
</body>
|
||
</html>
|
||
|