2021-09-03 17:50:55 +02:00
<!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 = "shortcut icon" href = "/favicon.ico?4" type = "image/x-icon" / >
< link href = "/css/bootstrap.min.css?3" rel = "stylesheet" >
< link href = "/css/telegram.css?212" 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.< / p >
< p > An error is characterized by several parameters:< / p >
2021-10-26 22:20:07 +02:00
< h4 > < a class = "anchor" href = "#error-code" id = "error-code" name = "error-code" > < i class = "anchor-icon" > < / i > < / a > Error Code< / h4 >
2021-09-03 17:50:55 +02:00
< 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 >
2021-10-26 22:20:07 +02:00
< h4 > < a class = "anchor" href = "#error-type" id = "error-type" name = "error-type" > < i class = "anchor-icon" > < / i > < / a > Error Type< / h4 >
2021-09-03 17:50:55 +02:00
< 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 >
< hr >
2021-10-26 22:20:07 +02:00
< h4 > < a class = "anchor" href = "#error-constructors" id = "error-constructors" name = "error-constructors" > < i class = "anchor-icon" > < / i > < / a > Error Constructors< / h4 >
2021-09-03 17:50:55 +02:00
< 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 >
2021-10-26 22:20:07 +02:00
< 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 >
2021-09-03 17:50:55 +02:00
< p > The request must be repeated, but directed to a different data center.< / p >
2021-10-26 22:20:07 +02:00
< 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 >
2021-09-03 17:50:55 +02:00
< 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 >
2021-10-26 22:20:07 +02:00
< p > In all these cases, the error description’
< 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 >
2021-09-03 17:50:55 +02:00
< 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 >
2021-10-26 22:20:07 +02:00
< 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 >
2021-09-03 17:50:55 +02:00
< 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_Х < / 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 >
< li > MSG_WAIT_FAILED: A request that must be completed before processing the current request returned an error< / li >
2021-10-26 22:20:07 +02:00
< li > MSG_WAIT_TIMEOUT: A request that must be completed before processing the current request didn't finish processing yet< / li >
2021-09-03 17:50:55 +02:00
< / ul >
2021-10-26 22:20:07 +02:00
< h3 > < a class = "anchor" href = "#401-unauthorized" id = "401-unauthorized" name = "401-unauthorized" > < i class = "anchor-icon" > < / i > < / a > 401 UNAUTHORIZED< / h3 >
2021-09-03 17:50:55 +02:00
< p > There was an unauthorized attempt to use functionality available only to authorized users.< / p >
2021-10-26 22:20:07 +02:00
< 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 >
2021-09-03 17:50:55 +02:00
< 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 unavailble for temporary authorization key, not bound to permanent< / li >
< / ul >
2021-10-26 22:20:07 +02:00
< h3 > < a class = "anchor" href = "#403-forbidden" id = "403-forbidden" name = "403-forbidden" > < i class = "anchor-icon" > < / i > < / a > 403 FORBIDDEN< / h3 >
2021-09-03 17:50:55 +02:00
< p > Privacy violation. For example, an attempt to write a message to someone who has blacklisted the current user.< / p >
2021-10-26 22:20:07 +02:00
< 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 >
2021-09-03 17:50:55 +02:00
< p > An attempt to invoke a non-existent object, such as a method.< / p >
2021-10-26 22:20:07 +02:00
< 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 >
2021-09-03 17:50:55 +02:00
< p > Similar to < a href = "#400-bad-request" > 400 BAD_REQUEST< / a > , but the app should not display any error messages to user in UI as a result of this response. The error message will be delivered via < a href = "/constructor/updateServiceNotification" > updateServiceNotification< / a > instead.< / p >
2021-10-26 22:20:07 +02:00
< h3 > < a class = "anchor" href = "#420-flood" id = "420-flood" name = "420-flood" > < i class = "anchor-icon" > < / i > < / a > 420 FLOOD< / h3 >
2021-09-03 17:50:55 +02:00
< 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 >
2021-10-26 22:20:07 +02:00
< h4 > < a class = "anchor" href = "#error-example" id = "error-example" name = "error-example" > < i class = "anchor-icon" > < / i > < / a > Error Example:< / h4 >
2021-09-03 17:50:55 +02:00
< ul >
< li > FLOOD_WAIT_X: A wait of X seconds is required (where X is a number)< / li >
< / ul >
2021-10-26 22:20:07 +02:00
< h3 > < a class = "anchor" href = "#500-internal" id = "500-internal" name = "500-internal" > < i class = "anchor-icon" > < / i > < / a > 500 INTERNAL< / h3 >
2021-09-03 17:50:55 +02:00
< 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 >
2021-10-26 22:20:07 +02:00
< 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 >
2021-09-03 17:50:55 +02:00
< / 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/blog" > Blog< / a > < / li >
< li > < a href = "//telegram.org/jobs" > Jobs< / 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/dl/android" > Android< / a > < / li >
< li > < a href = "//telegram.org/dl/wp" > Windows Phone< / 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 = "https://twitter.com/telegram" target = "_blank" data-track = "Follow/Twitter" onclick = "trackDlClick(this, event)" > Twitter< / a > < / h5 >
< / div >
< / div >
< / div >
< / div >
< script src = "/js/main.js?42" > < / script >
< script > b a c k T o T o p I n i t ( " G o u p " ) ;
removePreloadInit();
< / script >
< / body >
< / html >
