← 所有文章
教程

Telegram API_ID_PUBLISHED_FLOOD 错误怎么解决：恢复清单

API_ID_PUBLISHED_FLOOD 表示 Telegram 已将本次授权使用的 api_id 识别为公开凭据，或认为它不适合已发布应用。应立即停止用该凭据重试，确认构建是否复制了 Telegram 的受限示例 API ID，或自己的应用凭据是否被公开，再迁移到为自有应用申请的 API ID。Telegram 没有为此错误公开自助解封或轮换接口。

要点速览

  • Telegram 明确说明，开源客户端中的示例 API ID 只适合测试；在已发布应用中使用会触发 API_ID_PUBLISHED_FLOOD。
  • Telegram API 条款要求应用获取自己的 api_id，复制其他项目的凭据对不是生产方案。
  • API_ID_INVALID、API_ID_PUBLISHED_FLOOD、AUTH_KEY_DUPLICATED 与 SESSION_REVOKED 的原因不同，处理方式也不同。
  • 排查时不要输出 api_hash、登录验证码、QR token 或导出的 session。
  • 如果要连接普通 Telegram 账号，BotFather token 不能替代 API ID/API hash。

Telegram API_ID_PUBLISHED_FLOOD 的解决方法

这是应用凭据问题，不是“等待后继续重试”的提示。Telegram 在 auth.exportLoginToken 文档中将它列为 400：API ID 曾被公开，因此当前不能使用。官方应用创建指南还给出常见原因——Telegram 开源客户端包含用于测试的受限示例 API ID，但正式发布的应用必须使用自己的 ID。

先按错误类型分流：

错误Telegram 的定义下一步
API_ID_PUBLISHED_FLOODAPI ID 已公开，或受限示例 ID 被用于测试之外暂停新授权；查明凭据来源，用自有应用凭据对替换示例或共享凭据
API_ID_INVALIDapi_id 与 api_hash 组合无效确认两者来自同一应用，并检查配置解析是否改写了值
AUTH_KEY_DUPLICATED同一个 authorization key 被冲突的并行主 session 使用生成新的 authorization key 并重新登录；仅更换 API ID 不是官方给出的处理方式
SESSION_REVOKED用户已终止或作废授权使用正确的应用凭据重新进行用户授权
FLOOD_WAIT_X尝试次数过多严格等待服务端给出的时间，不要继续高频重试

本文与已有的 API ID/API hash 与 bot token 对比 意图不同：旧文帮助选择凭据，本文从 MTProto 授权已经失败的现场开始。

第一步：确认 API ID 的来源

追踪配置值，但不要打印原值。只记录安全指纹、部署名称和配置来源，并检查：

  1. 构建是否复制了 Telegram 开源客户端中的示例 ID；
  2. 同一凭据对是否出现在公开仓库、软件包、镜像、浏览器 bundle、文档示例、issue 或 CI 日志中；
  3. 多个产品或客户是否共用了一组本不应共享的应用凭据；
  4. 错误发生在 code login、QR login，还是两者都会发生。

Code 与 QR login 都需要客户端应用的 api_id 和 api_hash。QR 只改变用户确认登录的交互，并不会替换应用凭据。Telegram 的 auth.exportLoginToken 同时要求这两个字段，也明确可能返回 API_ID_PUBLISHED_FLOOD。

第二步：取得正确的应用凭据

客户端应用应登录 my.telegram.org，进入 API development tools，创建或查看与当前 Telegram 手机号关联的 API ID 与 API hash。Telegram 当前说明每个号码只能关联一个 API ID。

这一限制意味着不能承诺官方未提供的即时轮换流程。如果错误值只是 Telegram 示例或其他项目的凭据，换成自有应用凭据对就是清晰的官方路径。如果自有 API ID 已公开并被拒绝，应先移除公开内容、保留不含密钥的证据，再通过 Telegram 官方支持渠道处理具体账号，不要假设重复请求会自动恢复。

api_hash 只应保留在服务端，通过凭据存储在运行时注入，禁止进入浏览器 bundle，并在日志和错误追踪系统中遮蔽。QR token、验证码、2FA 信息与导出 session 是生命周期更短、但同样敏感的独立秘密。

第三步：安全迁移与复测

  • 冻结所有继续使用被拒绝 ID 的新登录请求。
  • 只在一个测试环境更新凭据引用，不要把密钥粘贴进源码。
  • 发起一次受控的 code 或 QR 授权，只记录错误类型、请求阶段和时间戳。
  • 授权成功后，先核对实际连接的账号身份，再逐步开放流量。
  • 逐批发布并观察 FLOOD_WAIT_X、SESSION_REVOKED 和异常的重复 session 错误。
  • 从部署清单、示例、缓存的 CI 产物和支持文档中移除旧凭据引用。

不要把可用的旧 session 当成底层应用凭据健康的证明。Session 与 API ID 位于授权流程的不同层次，旧 session 不能验证新的登录路径。

UnifyPort 在哪里承接

UnifyPort 的普通 Telegram 账号授权沿用同一应用边界：code 模式需要 provider_data.api_id、provider_data.api_hash 和 provider_data.phone；QR 模式仍需要 API ID 与 API hash。Telegram 授权指南列出了 code、QR、2FA 与 session 的真实步骤。

如果 Telegram 拒绝应用凭据，UnifyPort 不能把该凭据变为有效、代替你创建 Telegram API ID，或把 BotFather token 转成普通账号 session。应先解决 Telegram 凭据问题，再重启对应授权流程。

授权完成后，入站消息可作为标准化的 message.received 事件投递。下游 webhook 可参考 Telegram 到 Slack relay 构建指南，但应与凭据恢复分开处理。

限制与取舍

如果独立 bot 身份满足需求，应优先使用官方 Bot API。Bot token 专门服务这种模式，也不需要普通账号登录，但它不能代表现有个人账号。

只有确实需要普通账号身份时才使用 MTProto 用户授权。它会生成敏感 session，并继续受到 Telegram API 条款与自动滥用控制约束。非官方接口不能取消这些规则、保证恢复被拒绝的 API ID，也不能授权批量发送未经请求的消息。

FAQ

Telegram API_ID_PUBLISHED_FLOOD 是什么原因？

Telegram 给出两个直接信号：auth.exportLoginToken 在 API ID 曾公开时返回此错误；应用创建指南则说明，把开源客户端中的受限示例 API ID 用于正式应用会触发该错误。

等一段时间能恢复 API_ID_PUBLISHED_FLOOD 吗？

Telegram 没有把它描述为带等待时间的 FLOOD_WAIT_X，也未公开自助解封时长。应停止重试，用自有应用凭据替换示例或借用凭据；若自有 ID 已泄露，则走官方支持处理。

API_ID_INVALID 是同一个错误吗？

不是。API_ID_INVALID 表示 API ID/API hash 组合无效；API_ID_PUBLISHED_FLOOD 表示 ID 被识别为已经公开或不适合当前用途。修改 session 或凭据前先核对准确错误码。

BotFather token 能替代被拒绝的 API ID 吗？

不能用于普通账号授权。Bot token 只在 Bot API 中认证 bot；现有用户账号的 code 与 QR login 仍需要应用 API ID 和 API hash。

为了对比环境，可以把 API hash 写进日志吗？

不可以。应比较单向指纹或 secret 版本标识。API hash、验证码、QR token、2FA 信息和 session 导出都不应进入日志、工单、截图或公开示例。

下一步

先用 Telegram 的官方应用创建指南确认集成使用自己的 API ID。修正凭据来源后，再按 UnifyPort Telegram 授权指南完成一次受控的 code 或 QR 授权。

来源

来源与产品文档核验日期：2026-08-10。