错误处理

使用 API 时会有错误，必须在客户端正确处理。
误差由多个参数来表征：

错误代码

数值类似于HTTP状态。包含发生错误类型的信息：例如，数据输入错误、隐私错误或服务器错误。这是必填参数。

错误类型

一个形式的字符串文字，总结了问题。例如， 。这是一个可选参数。/[A-Z_0-9]+/AUTH_KEY_UNREGISTERED

错误数据库

API中所有方法都能返回的完整可读JSON错误列表可在此处找到，以下是其字段的描述：

• errors- 每个方法（对象）的所有错误信息和代码。
  • 键：错误代码作为字符串（数字字符串）
  • 值：每个方法（对象）的所有错误信息
    • 键：错误消息（字符串）
    • 值：一组可能触发该错误的方法数组（字符串数组，任何方法都可能发出错误时为空）
• descriptions- 对中提及的每个错误（以及与特定方法无关的其他一些错误）的描述errors
  • 说明：错误信息
  • 值：错误描述
• user_only- 仅限用户使用而非机器人可使用的方法完整列表。
• bot_only- 仅机器人可使用而非用户可使用的方法完整列表。
• business_supported- 通过 invokeWithBusinessConnection ，提供机器人可通过业务连接使用的方法完整列表。
• unauthed_allowed- 尚未登录连接可使用的方法完整列表。

错误消息和错误描述可能在关键字位置包含占位符，目前仅用于将错误消息中的时长映射到错误描述。printf%d

示例：

{ "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" ], "business_supported": [ "messages.sendMessage" ], "unauthed_allowed": [ "auth.sendCode" ] }

---

错误构造子

应该有办法处理rpc_error构造器中返回的错误。

以下是错误代码及其含义列表：

303 SEE_OTHER

请求必须重复，但必须指向不同的数据中心。

错误示例：

• FILE_MIGRATE_X：要访问的文件目前存储在不同的数据中心。
• PHONE_MIGRATE_X：用户试图用来授权的电话号码关联的是另一个数据中心。
• NETWORK_MIGRATE_X：源IP地址关联到不同的数据中心（用于注册）
• USER_MIGRATE_X：用于执行查询的用户身份关联到不同的数据中心（用于注册）

在所有这些情况下，错误描述的字符串字面量都包含了必须发送该重复查询的数据中心编号（而非X）。关于数据中心间重定向的更多信息 »

400 BAD_REQUEST

查询包含错误。如果请求是通过表单创建且包含用户生成的数据，应通知用户必须在重复查询前修正数据。

错误示例：

• FIRSTNAME_INVALID：名字无效
• LASTNAME_INVALID：姓氏无效
• PHONE_NUMBER_INVALID：电话号码无效
• PHONE_CODE_HASH_EMPTY：phone_code_hash 缺失了
• PHONE_CODE_EMPTY：phone_code不见了
• PHONE_CODE_EXPIRED：确认码已过期
• API_ID_INVALID：api_id/api_hash组合无效
• PHONE_NUMBER_OCCUPIED：电话号码已经在使用中了
• PHONE_NUMBER_UNOCCUPIED：电话号码尚未被使用。
• USERS_TOO_FEW：用户不足（比如说，无法创建聊天）
• USERS_TOO_MUCH：用户数已超过（例如创建聊天室的上限）
• TYPE_CONSTRUCTOR_INVALID：类型构造函数无效
• FILE_PART_INVALID：文件零件号无效
• FILE_PARTS_INVALID：文件部分数量无效
• FILE_PART_X_MISSING：文件的第X部分（其中X是数字）从存储中缺失
• MD5_CHECKSUM_INVALID：MD5校验和不匹配
• PHOTO_INVALID_DIMENSIONS：照片尺寸无效
• FIELD_NAME_INVALID：名为FIELD_NAME的字段无效
• FIELD_NAME_EMPTY：名为FIELD_NAME的字段缺失

401 未授权

曾有未经授权的尝试，试图使用仅授权用户可用的功能。

错误示例：

• AUTH_KEY_UNREGISTERED：密钥未在系统中注册
• AUTH_KEY_INVALID：钥匙无效
• USER_DEACTIVATED：该用户已被删除/停用
• SESSION_REVOKED：由于用户终止了所有会话，授权已被无效
• SESSION_EXPIRED：授权已过期
• AUTH_KEY_PERM_EMPTY：该方法不可用于临时授权密钥，且不绑定为永久授权

403 禁止

侵犯隐私。例如，试图给已将当前用户列入黑名单的人发送消息。

404 NOT_FOUND

尝试调用不存在的对象，比如方法。

406 NOT_ACCEPTABLE

类似于400 BAD_REQUEST，但应用必须以稍微不同的方式显示错误信息。接收构造函数时
不要向用户显示任何可见错误：相反，等待 updateServiceNotification 更新，并像往常一样处理。
基本上，更新服务通知更新会在406发出后立即独立发布（即作为内部的更新构造函数，而是普通更新）：更新会包含实际的本地化错误信息，通过界面弹窗向用户展示。rpc_errorpopuprpc_resultrpc_error

例外是错误，只有当任何非媒体DC检测到授权会话从两个不同IP地址的两个不同TCP连接并行发送请求时，才会发出错误。
请注意，媒体数据中心仍然允许并建议并行连接。
另外请注意，我们所说的会话是指通过授权构造函数识别的已登录会话，可通过account.getAuthorizations获取，而非MTProto会话。AUTH_KEY_DUPLICATED

如果客户端收到错误，表示会话已被服务器取消，用户必须生成新的认证密钥并重新登录。AUTH_KEY_DUPLICATED

420 洪水

使用给定输入参数调用该方法的最大允许次数已被超过。例如，尝试请求大量短信（SMS）以获取同一电话号码。

错误示例：

• FLOOD_WAIT_X：需要等待X秒（其中X为数字）
• FLOOD_PREMIUM_WAIT_X：需要等待X秒（其中X为数字）;用户也可以购买Telegram高级订阅以解除此限制。请点击这里»了解如何处理此错误的更多信息。

500 内部

在请求处理过程中发生了内部服务器错误;例如，访问数据库或文件存储时发生了中断。

如果客户收到500错误，或者您认为该错误不应发生，请尽可能收集有关查询和错误的信息并发送给开发者。

其他错误代码

如果服务器返回的错误代码与上述列出的代码不同，可能被视为与500错误相同，并被视为内部服务器错误。