Midday 邮件账户同步报 InboxAuthError 需要重新授权时怎么排查【免费下载链接】middayInvoicing, Time tracking, File reconciliation, Storage, Financial Overview your own Assistant made for Freelancers项目地址: https://gitcode.com/GitHub_Trending/mi/middayMidday 的 Inbox 功能通过 OAuth 2.0 连接 Gmail 和 Outlook定时扫描收件箱并把收据、发票附件同步进 Midday inbox。当访问令牌过期、刷新令牌失效或权限被收回时同步任务会抛出结构化的InboxAuthError账户被标记为disconnected之后的新收据不再被同步。这篇文档基于midday/inbox包的错误处理文档和同步任务源码说明如何确认这个错误、判断它是否必须重新授权以及重新授权后如何验证同步恢复。适用对象是自部署或本地运行 Midday 的开发者以及遇到收件箱同步中断的普通用户。先区分 InboxAuthError 和其他同步错误midday/inbox把错误分成两类见 packages/inbox/README.mdInboxAuthError认证/授权失败携带code、provider、requiresReauth三个字段InboxSyncError非认证类的瞬时同步问题限流、网络通常可重试isRetryable()对network_error和rate_limited返回true。InboxAuthError的错误码及是否需要重新授权如下来自 packages/inbox/README.mdCode含义需要重新授权token_expired访问令牌过期通常是token_invalid访问令牌无效是refresh_token_expired刷新令牌过期通常 90 天是refresh_token_invalid刷新令牌缺失或无效是unauthorized通用 401 错误是forbidden权限被拒绝403是consent_required用户需要重新同意权限Outlook是mfa_required需要 MFA 挑战Outlook是完整定义在 packages/inbox/src/errors.ts。按 README 的示例可以用类型守卫读取错误字段import { InboxAuthError, isInboxAuthError } from midday/inbox/errors; try { await connector.getAttachments(options); } catch (error) { if (isInboxAuthError(error)) { console.log(error.code); // token_expired | refresh_token_invalid | ... console.log(error.provider); // gmail | outlook console.log(error.requiresReauth); // true user must reconnect if (error.requiresReauth) { // Mark account as disconnected, prompt user to reconnect } else { // Transient error, retry may succeed } } }判断是必须重新授权还是等待自动重试同步任务 packages/jobs/src/tasks/inbox/provider/sync-account.ts 和定时同步处理器 apps/worker/src/processors/inbox/sync-scheduler.ts 对这两类错误的处理方式不同requiresReauth为true账户被标记为disconnectederrorMessage写入固定格式的错误信息Authentication failed (${error.code}): ${error.message}同时日志中会记录accountId、errorCode、errorMessage、requiresReauth、provider五个字段日志内容为Inbox sync failed - authentication error和Account marked as disconnected - requires reauth。此时需要用户手动重新授权。requiresReauth为false任务不改连接状态只记录Transient auth error - will retry交给 job 的重试机制处理。在重试之前连接器还会做一次自动补救packages/inbox/src/connector.ts 的getAttachments捕获到InboxAuthError且不需要重新授权时会调用provider.refreshTokens()刷新令牌后重发一次请求刷新后仍失败才把错误向上抛出。README 也说明两个 provider 都有主动刷新机制令牌在过期前 5 分钟刷新、同一时间只允许一个刷新操作、刷新后的令牌自动写回数据库。所以排查的第一步是看账户状态能拿到 worker 日志时确认requiresReauth的值如果是InboxSyncError限流、网络错误不改变连接状态等重试即可不需要用户操作。执行重新授权确认需要重新授权后在 Midday 的 Inbox 设置页Inbox → Settings操作具体步骤来自官方文档 connect-gmail.mdx 和 connect-outlook.mdxGmail打开 Inbox → Settings点击 Gmail 旁边的Reconnect重新登录 Google 账户并在权限页点击Allow连接成功后会跳回 Midday。文档说明 Google 出于安全考虑可能定期要求重新授权这属于预期行为。Outlook打开 Inbox → Settings点击 Outlook 旁边的Reconnect重新登录 Microsoft 账户、确认权限后点击Accept。Outlook 有两个需要额外注意的情况对应错误码表中的特殊 codeconsent_required用户必须重新同意权限重新走一次 Reconnect 授权流程mfa_requiredMicrosoft 端要求 MFA 挑战登录时完成多因素认证即可。对于 Microsoft 365 或工作/学校账户组织策略会限制第三方应用连接IT 管理员可能需要先允许该应用工作账户可能还需要管理员同意admin consent。connect-outlook 文档建议工作账户遇到连接问题时直接联系 IT 管理员。验证同步已恢复重新授权完成后按以下顺序确认手动触发一次同步在 Inbox → Settings 中点击 Gmail/Outlook 旁边的Sync now不必等定时扫描看账户状态同步成功后任务会把账户status更新为connected、清空errorMessage并更新lastAccessed见 sync-account.ts 的成功路径。如果状态仍是disconnected且errorMessage仍是Authentication failed (...)说明授权未真正生效回到上一步检查是否登录了正确的账户等几分钟看新收据新邮件可能需要几分钟才会被处理这是 connect-gmail 和 connect-outlook 文档都提到的正常延迟。如果重新授权后同步正常但个别收据仍未被捕获参考 troubleshooting.mdx 中Gmail/Outlook not capturing receipts一节确认连接在 Inbox Settings 中仍为活动状态、垃圾邮件/ Junk 文件夹不会被扫描Outlook 使用 Focused Inbox 时两个视图都会扫描无需切换、个别收据可以手动转发到已连接邮箱地址作为备用。限制与边界已经在 Midday inbox 中的收据在断开和重新连接过程中不会丢失重新授权只影响之后新增的同步requiresReauth为false的瞬时认证错误和所有InboxSyncError都由重试机制处理不需要用户介入账户状态不会被改成disconnected文档没有给出刷新令牌过期的确切天数保证refresh_token_expired的描述是typically 90 days即 Google 侧典型值为 90 天自部署时Gmail 连接依赖环境变量GMAIL_CLIENT_ID、GMAIL_CLIENT_SECRET、GMAIL_REDIRECT_URIOutlook 依赖OUTLOOK_CLIENT_ID、OUTLOOK_CLIENT_SECRET、OUTLOOK_REDIRECT_URI见 packages/inbox/README.md。连接按钮不可用或授权后回调失败时先检查对应 provider 的三个变量是否配置完整文档未提供针对单个错误码的服务器侧修复手段forbidden403这类权限被拒的情况除重新授权外没有其他文档化路径工作账户可联系 IT 管理员。【免费下载链接】middayInvoicing, Time tracking, File reconciliation, Storage, Financial Overview your own Assistant made for Freelancers项目地址: https://gitcode.com/GitHub_Trending/mi/midday创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考