CINXE.COM

<!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>