错误码

Warmbly API 使用标准 HTTP 状态码，并以 JSON 格式返回结构化错误响应。

错误响应格式

所有错误均采用以下结构：

{
  "error": "Error Type",
  "message": "Human-readable description of what went wrong.",
  "code": "machine_readable_code",
  "request_id": "req_or_uuid_for_support"
}

error 和 message 供用户阅读。客户端逻辑应使用 code、HTTP 状态码及 retry_after 等端点特有字段。联系支持时，请附上 request_id。

HTTP 状态码

发送准入诊断

这些错误码出现在营销活动动态和任务失败元数据中，不是 HTTP 响应状态码：

分发前的准入拒绝会释放发送预留，不消耗一次失败发送尝试。遭拒的统一收件箱发送以 failed 状态结束，不会重试，并向邮箱所有者报告。独立可配置上限及每日目标量，参见 营销活动 和 发送行为。

客户端错误（4xx）

服务端错误（5xx）

错误详情

400 Bad Request（请求无效）

请求因语法无效而无法处理时返回。

常见原因：

• 请求体中的 JSON 无效
• 缺少必填字段
• 字段类型无效
• 值超出允许范围

示例：

{
  "error": "Bad Request",
  "message": "The request body is missing or has invalid fields: \"to\" is required; \"subject\" is required.",
  "code": "bad_request",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

无法读取请求体时，message 会说明原因：

字段以 JSON 键名标识，嵌套字段采用点分路径（inner.name）。所有情况下，code 均为 bad_request，因此应依据 code 分支处理，并显示或记录 message。

带版本的 API 路由在端点运行前检查每个查询参数的名称和值，包括直接读取筛选条件的端点。旧版别名 /invitations/lookup 采用相同验证。NUL 字符、无效 UTF-8 和格式错误的查询编码会返回 400，而不会将不支持的文本传给数据库。例如，?q=%00 返回 Query parameter "q[0]" contains a NUL character, which is not supported.。有效 Unicode 文本和正确编码的标点保持不变。

邮箱、营销活动和联系人路由上的资源 ID 必须为 UUID。邮箱的 tags 及营销活动的 email_tags、folders 数组也要求 UUID 值。格式无效的值会在写入数据库之前返回 400，并带有 code: "bad_request" 和 request_id。有效 UUID 会被规范化，重复关系 ID 会去重；工作区归属检查仍然适用。

解决方法：

• 检查 JSON 是否有效
• 确认所有必填字段均已提供
• 确保字段值符合预期类型
• 将请求体结构与端点参考页面对照：某些端点接受数组，多数接受对象

具体 400 错误码：

密码被拒绝的情况

密码须为 8 至 128 个字符。不要求特定字符组合，但会不区分大小写地与英国国家网络安全中心发布的 100,000 个最常泄露密码比对。

{
  "error": "Bad Request",
  "message": "This password appears in a public list of breached passwords. Choose one that does not.",
  "code": "password_breached",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

App Attest 验证被拒绝的情况

原生应用在登录、注册和密码重置时通过 App Attest 证明自身身份，以替代验证码。

每个已注册密钥每小时最多执行 30 次受保护调用。超过后返回 400，错误码为 bad_request，消息为 Too many attempts, please try again later.，与其他登录尝试额度的响应相同。

{
  "error": "Bad Request",
  "message": "We couldn’t verify this copy of the app. Update it from the App Store and try again.",
  "code": "app_attest_failed",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

Cloud 连接被拒绝的情况

Warmbly Cloud 预热被拒绝的情况

由 Warmbly Cloud 预热的邮箱必须通过云端更改预热设置（参见 预热设置）。无法执行时，PATCH /emails/:id 及预热启动、暂停和恢复路由会返回以下错误。所有情况下，实例均不会应用此次更新的其余部分。在 cloud_warmup_not_applied 之后，邮箱本地保存的 Warmbly Cloud 设置仍会刷新为 Cloud 报告的值。使用相同 Idempotency-Key 重放会返回已保存响应，因此请使用新键重试。

名称被拒绝的情况

名称会显示给其他人，包括出现在邀请和通知邮件中，因此仅允许纯文本。控制台、API、设置页面及 warmblyctl 采用相同规则：

• 名或姓最多 50 个字符，且包含字母；工作区或公司名称最多 64 个字符，且包含字母或数字；邮箱显示名称仍采用自身的 2 至 100 个字符限制
• 不得包含链接、网址或邮箱地址：不得含有 @、//、www. 或 https: 等协议前缀，也不得含有 example.com 这样的主机名或 IP 地址。全角点和中文句号也按点处理
• 不得包含控制字符、不可见格式字符（零宽字符和双向覆盖字符）、<、>、` 或 \，也不得叠加超过三个组合附加符号
• 去除首尾空格，连续空格合并为一个，并以此规范化形式保存
• OAuth 应用名称不得包含 Warmbly，包括插入空格或使用相似字符的写法。已有此类名称的应用在名称更改前保留原名

{
  "error": "Bad Request",
  "message": "First name cannot contain a link, web address or email address.",
  "code": "invalid_name",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

来自 Google、Apple 或单点登录服务商的名称若违反规则，会被丢弃而不会拒绝登录，并在接入流程中要求重新填写。

邮箱导入被拒绝的情况

邮箱导入 路由（/emails/imports）返回这些错误。某行连接失败不是 HTTP 错误：导入对象会记录该行，原因位于其 cause（参见 指南）。

{
  "error": "Conflict",
  "message": "This row's credentials were removed after the retry window. Import it again.",
  "code": "mailbox_import_credentials_expired",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

邮箱来源被拒绝的情况

邮箱供应商 路由（/emails/vendors）、管理员授权 路由（/emails/grants）和 发件域名 路由（/emails/domains）返回这些错误。在导入内部，供应商和授权失败改为记录在行的 cause 中（参见 指南）。

{
  "error": "Bad Request",
  "message": "This sign-in expired or belongs to someone else. Start again.",
  "code": "mailbox_grant_state_invalid",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

切换应用专用密码被拒绝的情况

POST /emails/onboarding/app-password/:id 会 将邮箱从逐邮箱 Google 登录迁移 至应用密码方式。除以下错误外，Gmail 拒绝密码时会返回与 SMTP/IMAP 连接相同的错误码，例如 mailbox_auth_refused。任何拒绝均不会更改内容。

投递位置测试被拒绝的情况

收件箱投递位置测试 路由（/placement/* 和 /campaigns/:id/placement-monitor）返回这些错误。遭拒的测试不会发送任何邮件：所有检查均在安排第一份副本之前执行。

批次在创建前执行所有适用于整个批次的检查（邮件内容、种子邮箱组、跟踪、额度及同意使用的积分），并以上述错误码拒绝。各邮箱的检查在轮到它时执行：届时遭拒的邮箱会延后或跳过，其在 GET /placement/batches/:id/senders 中的发件邮箱行以 reason 携带错误码，以 detail 携带说明句。除单次测试错误码外，发件邮箱行还可能包含 placement_sender_deleted（邮箱已从工作区移除）、placement_batch_retry_expired（七天重试窗口结束时仍不可用）、placement_batch_start_failed（多次尝试后仍无法启动测试）及 placement_batch_copy_unavailable（被测营销活动或步骤已删除，因此跳过所有尚未开始的邮箱）。

{
  "error": "Conflict",
  "message": "This test sends 40 emails from [email protected], which has 12 left of its daily limit today.",
  "code": "placement_daily_budget",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

未带这些错误码的 400 表示请求格式有误：panel 或 tracking 未知、提供 sequence_id 却没有对应 campaign_id、临时测试缺少主题或正文、监控 interval_days 超出 1 至 30 或 alert_below 超出 0 至 100，或批次将 pace 设为 quick、同时提供或均未提供 sender_account_ids 和 sender_scope、sender_scope.type、sample.mode 或 on_unavailable 未知，或在非 random/percent 抽样中提供 sample.stratify。

OAuth 应用与社区目录操作被拒绝的情况

POST /oauth/applications 注册应用，PUT /oauth/applications/:id/listing 发布或编辑其 社区目录条目。任何拒绝均不会保存内容。

凭据管理操作被拒绝的情况

OAuth 同意和令牌端点改用 RFC 6749 结构（error、error_description）。GET /oauth/authorize/details 或 POST /oauth/authorize 返回 access_denied，表示批准成员的角色不覆盖任何请求权限范围。刷新时返回 invalid_grant，表示令牌未知、已过期、已撤销、已经使用（同时撤销授权），或其成员已不再拥有任何已授予权限范围。服务器内部失败返回 500 server_error，附带固定描述和 request_id。

CRM 服务商操作被拒绝的情况

工作区使用 HubSpot 或 Pipedrive 作为 CRM 时，由 CRM 端点返回。更改先写入服务商，再保存到 Warmbly，因此以下每项都表示两端均未更改。

{
  "error": "Conflict",
  "message": "Pipelines are managed in HubSpot. Edit them there and they update here within minutes.",
  "code": "crm_managed_externally",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

Salesforce 同步被拒绝的情况

Salesforce 端点返回自身错误码。若由 Salesforce 本身拒绝，message 携带其 errorCode 和文本，例如 Salesforce: INVALID_FIELD: No such column 'Tier__c' on entity 'Lead'。

Apollo 和 Clay 操作被拒绝的情况

Apollo 和 Clay 端点返回自身错误码。

自动化流程操作被拒绝的情况

mailbox_oauth_return_origin

带有 code: "mailbox_oauth_return_origin" 的 400 表示 Google 或 Microsoft 邮箱连接或重新授权来自后端不允许的控制台源地址。请按 共用后端的控制台配置 所述，将其精确 HTTP(S) 源地址添加到 CORS_ALLOW_ORIGINS。通配符不能充当 OAuth 返回允许列表。

401 Unauthorized（未通过身份验证）

身份验证失败时返回。

常见原因：

• 缺少 Authorization 请求头
• API 密钥格式无效
• API 密钥已过期
• API 密钥已撤销

示例：

{
  "error": "Unauthorized",
  "message": "Token not found.",
  "code": "unauthorized",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

解决方法：

• 包含 Authorization: Bearer wmbly_... 请求头
• 确认 API 密钥正确
• 检查密钥是否已过期或撤销
• 必要时生成新密钥

有两种 401 情况与 API 密钥无关。首次认领端点在设置链接无效、已使用或已过期时返回 setup_token_invalid。通过 warmblyctl setup-link 输出新链接，详见 首次运行。

POST /auth/sso/exchange 在兑换交接代码时未提供 POST /auth/<provider>/begin 发给登录发起浏览器的绑定密钥，则返回 sso_wrong_browser。交接被刻意设计为不可转移：转发的登录链接或在其他浏览器打开的链接不能使接收者登录。请在打算使用的浏览器中重新开始登录。

402 Payment Required（需要付款）

请求 AI 操作或使用积分支付的投递位置测试，但组织积分不足时返回。响应携带稳定错误码 insufficient_credits。

{
  "error": "Payment Required",
  "message": "You're out of AI credits. Add more to keep using the assistant.",
  "code": "insufficient_credits",
  "request_id": "req_..."
}

解决方法：

• 等待每月额度重置，或购买充值包（参见 AI 积分）
• 相关情况：错误码为 usage_cap_exceeded 的 429 表示触及短期 AI 用量上限；请稍后重试

投递位置测试也会返回 402，错误码为 placement_not_entitled 或 placement_quota_exceeded；参见 投递位置测试拒绝原因。付费投递位置测试超出积分余额时返回 insufficient_credits，超出支出上限时返回 429 和 usage_cap_exceeded；两者均不收费。

403 Forbidden（禁止访问）

已通过身份验证但缺少所需权限时返回。

常见原因：

• API 密钥缺少所需权限
• 请求 IP 不在允许列表中
• 邮箱账户不在允许列表中
• 组织访问受限
• 成员仅限访问选定资源（member_access_restricted）

示例：

{
  "error": "Forbidden",
  "message": "You don't have access to this feature.",
  "code": "forbidden",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

解决方法：

• 检查 API 密钥权限
• 若配置了 IP 限制，请核对
• 必要时申请更多权限

mailbox_gmail_oauth_disabled

code 为 mailbox_gmail_oauth_disabled 的 403 来自带有 provider: "gmail" 的 POST /emails/onboarding/oauth/start。后端没有完整的 Google 邮箱客户端凭据，或通过 BOX_GOOGLE_OAUTH_CONNECT 显式禁用新 Google OAuth 连接；GET /auth/config 将其声明为 gmail_oauth_connect: false。调用者权限并无问题。重新授权现有 Gmail 邮箱（POST /emails/onboarding/oauth/reauth/:id）绝不会因此遭拒。

{
  "error": "Forbidden",
  "message": "New Gmail mailboxes connect with an app password over IMAP and SMTP on this deployment, not with Google sign-in.",
  "code": "mailbox_gmail_oauth_disabled",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

解决方法：

• 通过 POST /emails/onboarding/smtp-imap 连接邮箱，使用 smtp.gmail.com:465 和 imap.gmail.com:993，两者均采用 TLS，并提供 Google 应用密码。参见 Gmail 与 Google Workspace
• 使用自有 Google 应用的实例必须同时设置 BOX_GOOGLE_CLIENT_ID 和 BOX_GOOGLE_CLIENT_SECRET。将 BOX_GOOGLE_OAUTH_CONNECT 留空或设为 true，然后在应提供 Google 登录的部署上启用 控制台显示开关

注册和邀请被拒绝的情况

注册和邀请拒绝携带各自的 code，使客户端可以根据具体条件分支处理，无需匹配文本。它们描述部署策略，绝不透露给定地址是否存在。

{
  "error": "Forbidden",
  "message": "This server is invite only. Ask an administrator to invite you, then open the link in the invitation to create your account.",
  "code": "registration_invite_only",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

解决方法： 在自托管部署中，这些属于配置行为，而非故障。参见 账户与访问。

需要确认

reauth_required 保护会发放长期凭据、披露签名密钥、更改访问者、不可撤销，或访问整个域邮件的更改。完整列表见 需要近期确认的操作。通过 GET /v1/auth/reauth/methods 列出账户可用的确认方式（包括通行密钥，以及关联的 Google、Apple 或单点登录身份；参见 端点）。使用密码或当前双重验证代码时：

curl -X POST "https://api.warmbly.com/v1/auth/reauth" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"password": "..."}'

{ "valid_for_seconds": 300 }

确认记录在会话上，并在返回的时间窗口内有效，因此连续执行相关更改只需确认一次。

启用双重身份验证（POST /auth/2fa/enroll/start 和 /confirm）同样受保护，因为已确认的认证器本身也可用于确认身份。有密码的账户按上述方式确认。既无密码也无 2FA 的账户（通过 Google、Apple 或单点登录创建）使用通行密钥或关联身份确认。若均无，则与其他需确认操作一样，可在登录后五分钟内执行；更早的会话返回 reauth_no_factor，需退出后重新登录。API 密钥和 OAuth 令牌没有可供确认的会话，因此这些路由仅能通过已登录会话访问；对于密钥创建，这是有意设计，否则泄露的密钥可能继续签发更多密钥。

{
  "error": "Forbidden",
  "message": "Confirm it is you before making this change.",
  "code": "reauth_required",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

成员访问范围

仅限访问 选定资源 的成员，以及代表该成员的 API 密钥或 OAuth 应用，只能访问按授权范围筛选的读取路由。范围相关拒绝如下：

超出受限调用者授权范围的营销活动或邮箱返回 404，与不存在的资源相同，因此不会通过权限范围泄露工作区中的其他资源。GET /unibox/thread/labels 对未知会话、位于所选工作区之外的会话，或可访问邮箱中没有任何邮件的会话，也返回相同的 404。可访问但无标签的会话返回空列表。

解析受限范围或范围内计数失败时，请求会失败，而不会返回工作区整体数据。实时授权查询错误会停止营销活动、邮箱和组织通道；无法验证授权的用户通道事件会被暂扣。参见 有时限的实时授权。

{
  "error": "Forbidden",
  "message": "Your access to this workspace is limited to selected campaigns and mailboxes, and this is outside it.",
  "code": "member_access_restricted",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

解决方法： 请具有 管理团队 权限的成员在 设置 > 成员 中扩大访问范围。

slack_link_email_mismatch

code 为 slack_link_email_mismatch 的 403 来自未提交 Slack 登录结果的 POST /integrations/slack/link。以这种方式确认 Slack 关联，要求 Slack 账户资料中的邮箱与已登录用户的 Warmbly 邮箱相同，比较时忽略大小写。代码仍可使用：请提供来自 POST /integrations/slack/link/verify 的 slack_code 和 state 再次确认。GET /integrations/slack/link/:code 通过 email_matches 提前报告匹配检查结果，并通过 verify_available 说明 Slack 登录是否可用。

{
  "error": "Forbidden",
  "message": "This Slack account's email is not the one you sign in to Warmbly with. Continue with Slack to confirm the account is yours.",
  "code": "slack_link_email_mismatch",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

解决方法：

• 使用 Slack 个人资料中的邮箱登录 Warmbly，然后再次确认
• 若地址已经相同，请具有 manage_settings 的成员在 集成 > Slack 中重新连接 Slack，使连接授予 users:read 和 users:read.email

404 Not Found（未找到）

请求的资源不存在时返回。

常见原因：

• 资源 ID 无效
• 资源已删除
• 资源属于其他组织
• 端点 URL 拼写错误

示例：

{
  "error": "Not Found",
  "message": "Resource not found.",
  "code": "not_found",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

解决方法：

• 确认资源 ID 正确
• 检查资源是否已删除
• 确保使用正确端点

具体 404 错误码：

409 Conflict（冲突）

请求与现有数据冲突时返回。

常见原因：

• 尝试创建已存在的资源
• 唯一值重复
• 尝试删除当前状态尚不允许删除的资源，例如仍可用于身份验证的 API 密钥

示例：

{
  "error": "Conflict",
  "message": "resource already exists",
  "code": "conflict",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

为已有账户的地址创建账户，会返回 409，使用通用 conflict 错误码，并提示登录或重置密码。启用邮箱验证时，邮件验证码证明地址属于调用者后，由 POST /auth/register/confirm 返回；未启用时则由 POST /auth/register 直接返回。

部分冲突具有独立 code。邮箱导入冲突见 邮箱导入拒绝原因。联系人的邮箱地址必须未被占用，因此将其改为另一联系人已使用的地址时会被拒绝，而不会合并两位联系人：

mailbox_cloud_unenroll_failed 表示自托管实例在删除过程中失去与 Warmbly Cloud 的联系。删除已加入预热池的邮箱时，必须先撤销加入关系，再移除记录，因为池中持有邮箱自身的 SMTP/IMAP 凭据，而该记录是唯一知道加入关系存在的地方。同一调用还会在移除记录前释放云端托管镜像，使邮箱返回云端工作区并可再次接管，而不会继续被已经不再保有它的实例认领。邮箱记录会保留。Warmbly 立即尝试将其恢复到工作节点；若失败，工作节点协调器可能稍后恢复。实例恢复云端连接后，请重试删除。先在 设置 > Warmbly Cloud 中取消加入并无帮助，因为它调用的是同一接口。

422 Unprocessable（无法处理）

请求数据验证失败时返回。

常见原因：

• 邮箱地址格式无效
• 字符串超过最大长度
• 数字超出有效范围
• 枚举值无效

示例：

{
  "error": "Unprocessable",
  "message": "validation failed",
  "code": "unprocessable",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

500 Internal Server Error（服务器内部错误）

服务器发生未预期错误时返回。

示例：

{
  "error": "Internal Server Error",
  "message": "Something went wrong.",
  "code": "internal_error",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

解决方法：

• 稍作等待后重试请求
• 若持续发生，请附带请求详情联系支持

500 始终携带相同消息。不返回底层详情，因为它通常是包含表名、列名和主机名的数据库或服务商输出，对调用者没有帮助。详情会与响应中的 request_id 关联记录，因此在支持请求中引用该 ID 即可关联两者。

有一种 internal_error 情况需要区分。身份验证端点无法发送邮件时，消息会明确说明，而不是报告通用故障，因为自托管实例上看到消息的人通常就是能够修复它的人：

{
  "error": "Internal Server Error",
  "message": "We couldn't send the email. If you administer this server, check the mail transport configuration.",
  "code": "internal_error",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

在自托管部署中，这涉及 MAIL_TRANSPORT 和 SMTP_ 变量。参见 自托管。

503 Service Unavailable（服务不可用）

服务暂时不可用时返回。

示例：

{
  "error": "Service Unavailable",
  "message": "service unavailable",
  "code": "service_unavailable",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

解决方法：

• 等待后采用指数退避重试
• 检查状态页面是否有故障事件

mailbox_provider_not_configured

code 为 mailbox_provider_not_configured 的 503 不是暂时性问题，重试无效。它表示部署未配置请求所需邮箱服务商的 OAuth 客户端，仅发生在自托管安装中。

{
  "error": "Service Unavailable",
  "message": "Gmail is not configured on this deployment. Set BOX_GOOGLE_CLIENT_ID and BOX_GOOGLE_CLIENT_SECRET in your .env, then restart.",
  "code": "mailbox_provider_not_configured",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

解决方法：

• 在安装根目录的 .env 中设置 BOX_GOOGLE_CLIENT_ID 和 BOX_GOOGLE_CLIENT_SECRET，或 BOX_OUTLOOK_CLIENT_ID 和 BOX_OUTLOOK_CLIENT_SECRET，然后重启
• 或改用 SMTP 和 IMAP 连接邮箱，无需这些配置
• 完整步骤：连接邮箱

ai_not_configured

code 为 ai_not_configured 的 503 不是暂时性问题，重试无效。它来自 POST /templates/analyze，表示部署完全没有配置 AI 服务商。客户端可据此区分“此处没有 AI”和“服务商暂时异常”；后者返回通用 service_unavailable，值得重试。

{
  "error": "Service Unavailable",
  "message": "AI analysis is not configured on this deployment.",
  "code": "ai_not_configured",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

解决方法：

• 在安装根目录的 .env 中设置 AI_PROVIDER 和 AI_API_KEY，然后重启。参见 配置参考
• 在客户端隐藏 AI 功能入口，而非重试：修改请求内容无法使其成功

slack_not_configured

code 为 slack_not_configured 的 503 不是暂时性问题，重试无效。实例未配置 Slack，仅发生在自托管安装中。未设置 SLACK_SIGNING_SECRET 时，三个 Slack 请求 URL（/api/v1/integrations/slack/events、/interactivity 和 /commands）都会返回此错误。

{
  "error": "Service Unavailable",
  "message": "Slack is not set up on this Warmbly instance.",
  "code": "slack_not_configured",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

解决方法：

• 创建实例的 Slack 应用，并在后端和消费者进程上设置 SLACK_OAUTH_CLIENT_ID、SLACK_OAUTH_CLIENT_SECRET 和 SLACK_SIGNING_SECRET，然后重启。参见 Slack 应用
• 客户端应从 GET /integrations/slack/status 读取 app_configured 和 interactive_configured，并隐藏 Slack 功能入口，而非重试

这些请求 URL 对 Slack 签名验证失败的请求返回 401 unauthorized。将 Slack 账户关联到自己并非成员的工作区，返回 403 forbidden；关联邮箱不属于自己的账户且未通过 Slack 登录验证时，返回 403 slack_link_email_mismatch。

mailbox_allowance_reached

code 为 mailbox_allowance_reached 的 403 可来自所有邮箱连接途径：POST /emails/onboarding/oauth/start、POST /emails/onboarding/oauth/finish、POST /emails/onboarding/smtp-imap，以及 POST /emails/onboarding/smtp-imap/bulk 内的逐行结果。邮箱导入 不以 HTTP 错误返回它：超出额度的行以 cause 为 allowance_reached 失败，额度提高后可重试。这不是权限问题：工作区已用完全部 邮箱数量额度，付费套餐中每日每包含一封发送量对应一个邮箱，免费工作区则为 10。未连接任何邮箱。

{
  "error": "Forbidden",
  "message": "This workspace holds 15000 of its 15000 mailboxes. Request an increase, or move to a plan with more daily sends.",
  "code": "mailbox_allowance_reached",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

解决方法：

• 先读取 GET /emails/allowance：remaining 表示还能成功连接多少个邮箱，pending_request 表示是否已申请增额
• 通过 POST /organization/:orgId/limit-requests 为 max_email_accounts 提交增额申请，或升级到每日发送量更高的套餐。申请获批会立即提高额度，届时重试连接
• 重新连接现有邮箱绝不会返回此错误码

storage_limit_reached

code 为 storage_limit_reached 的 400 来自 POST /campaigns/:id/attachments、POST /email-images，以及会复制附件的营销活动复制操作。工作区存储字节数（所有营销活动附件加邮件图片库）将超过配额。检查与写入在两者共用的单个工作区锁下完成，因此争抢最后剩余配额的两个上传无法同时通过。未存储任何内容。

{
  "error": "Bad Request",
  "message": "Storage limit reached: 51190 MB of 51200 MB used, 12 MB to add. Remove attachments or images, or upgrade your plan.",
  "code": "storage_limit_reached",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

解决方法：

• GET /organization/current/limits 报告 storage.used_bytes 和 storage.limit_bytes；若套餐变更导致工作区超额，还报告 storage.over_quota。无论是否超额，现有附件仍可继续发送
• 删除不再需要的附件（DELETE /campaigns/:id/attachments/:attachmentId）或图片（DELETE /email-images/:id），或升级到付费套餐以获得更大配额

mailbox_validation_timeout

code 为 mailbox_validation_timeout 的 400 来自 SMTP 和 IMAP 连接及重新授权端点。Warmbly 在保存任何内容前，通过实际连接邮件服务器验证凭据，但某一路连接在验证窗口内始终未响应。消息会指出未响应的一端，并说明另一端是否已成功登录。未保存任何内容，也未创建邮箱。

{
  "error": "Bad Request",
  "message": "SMTP (smtp.gmail.com:465) did not answer in time. IMAP (imap.gmail.com:993) signed in. Nothing was saved. Check the host and port, then try again. Port 465 did not answer and the worker could not use 587 with STARTTLS on the same server either. Some networks block outbound mail ports; check that the server is reachable from outside and which port it listens on.",
  "code": "mailbox_validation_timeout",
  "request_id": "6f3c0a1e-2d47-4c6b-9a1f-2b7c5f0e8d31"
}

同一错误码的消息若以 Warmbly's worker did not report back 开头，表示根本没有工作节点回应检查，因此邮件服务器从未被测试。检查依次交给每个健康工作节点，最多等待两个已接受却不回应的工作节点，因此此错误意味着整个节点集群都未响应。在托管产品上，请重试，持续失败则联系支持。在自托管实例上，请检查工作节点是否运行、是否有心跳，以及是否能访问与后端相同的 Redis：检查通过 Redis 到达工作节点，结果也通过同一路径返回。

解决方法：

• 阅读消息，确认哪一端未响应。一端通过而另一端挂起，说明问题在工作节点到该端口的网络，而非密码：无人监听或被防火墙丢弃数据包的端口会等待完整超时，而不会立即拒绝
• 465 始终未响应时，工作节点还会尝试同一服务器的 587 STARTTLS，连接成功则使用它；验证通过后保存的端口为 587。此错误表示两个端口均未响应，请检查服务器是否可从网络外部访问，以及实际监听哪个端口
• 请重试。负载较高的邮件服务器可能某次响应较慢，下次立即响应
• 确认服务器接受来自网络外部的连接，并确保安全模式与端口匹配：465 和 993 使用 tls，587 和 143 使用 starttls

mailbox_auth_refused

code 为 mailbox_auth_refused 的 400 来自 SMTP 和 IMAP 连接及重新授权端点。邮件服务器已响应，但拒绝登录。消息会指出哪一端、哪台服务器，引用服务器原始回复；对于 Google 服务器，还会说明应用密码的含义。未保存任何内容。

{
  "error": "Bad Request",
  "message": "SMTP (smtp.gmail.com:587) refused the sign-in: 535 5.7.8 Username and Password not accepted. IMAP (imap.gmail.com:993) refused the sign-in: imap: NO [AUTHENTICATIONFAILED] Invalid credentials (Failure). Nothing was saved. Google itself refused this address and password. Use a 16-letter app password from myaccount.google.com/apppasswords, created while signed in to the Google account that owns this address, and enter the account's own sign-in address rather than an alias or a group. A deleted app password stops working at once, and on Google Workspace the administrator can block app passwords or IMAP.",
  "code": "mailbox_auth_refused",
  "request_id": "6f3c0a1e-2d47-4c6b-9a1f-2b7c5f0e8d31"
}

解决方法：

• 阅读消息中的服务器回复：它说明哪一端拒绝，通常也说明原因（密码错误、需要应用密码、域名关闭 IMAP）
• 用户名通常为完整邮箱地址。账户启用两步验证时，密码应为服务商的应用密码，绝不能使用账户密码
• 空白字符不是问题：Warmbly 在所有途径都会去除密码首尾空白，对 Google 服务器使用的密码还会去除所有空格
• 对于 Google，使用真实应用密码仍遭拒时，几乎总是地址并非签发该密码的账户：请填写账户自己的登录地址，而非别名或群组；登录该账户后创建应用密码，并确认之后没有删除。在 Google Workspace 中，管理员也可能对组织禁用应用密码或 IMAP

mailbox_unreachable

code 为 mailbox_unreachable 的 400 来自同一组端点。工作节点完全无法连接服务器：域名解析失败、端口拒绝连接，或防火墙丢弃数据包。消息指出服务器和具体情况。未保存任何内容。

{
  "error": "Bad Request",
  "message": "SMTP (smtp.example.com:465) could not be reached from the worker: the port refused the connection. Nothing was saved.",
  "code": "mailbox_unreachable",
  "request_id": "6f3c0a1e-2d47-4c6b-9a1f-2b7c5f0e8d31"
}

解决方法：

• 检查主机和端口是否拼写错误
• 连接从工作节点发出，而非浏览器或 API 主机：工作节点所在网络必须能访问服务器的对应端口。部分托管服务商默认封锁外发邮件端口，需要申请开放

mailbox_tls_failed

code 为 mailbox_tls_failed 的 400 来自同一组端点。已连到服务器，但无法建立安全连接：证书不能通过该主机名验证、握手失败，或端口要求不同模式（在 STARTTLS 端口使用 tls，或反之）且服务器未提供 STARTTLS。未保存任何内容。

{
  "error": "Bad Request",
  "message": "IMAP (mail.example.com:143) did not complete a secure connection: the server offers no STARTTLS on this port. Nothing was saved.",
  "code": "mailbox_tls_failed",
  "request_id": "6f3c0a1e-2d47-4c6b-9a1f-2b7c5f0e8d31"
}

解决方法：

• 安全设置须与端口匹配：465 和 993 使用 tls，587 和 143 使用 starttls，除非服务商文档另有说明
• 使用证书签发的主机名，即服务商文档中的主机名，而非别名或 IP 地址

mailbox_server_declined

code 为 mailbox_server_declined 的 400 来自同一组端点。登录因凭据之外的原因无法完成：服务器要求稍后重试（4xx 回复，常见于登录限流）、未提供 Warmbly 实现的登录方式、返回与密码无关的 5xx（不支持某种机制、强制要求 STARTTLS）、协议交互中断，或探测在收到回复前自身失败。若服务器有回复，消息会携带该回复。未保存任何内容。

{
  "error": "Bad Request",
  "message": "SMTP (smtp.example.com:587) declined the sign-in for now and asks for a retry: 454 4.7.0 Too many login attempts, please try again later. Nothing was saved.",
  "code": "mailbox_server_declined",
  "request_id": "6f3c0a1e-2d47-4c6b-9a1f-2b7c5f0e8d31"
}

解决方法：

• 对于 4xx 回复，请等待几分钟后重试
• 若服务器仅提供 Warmbly 未实现的机制（NTLM、GSSAPI），请使用服务商文档中的 SMTP 提交主机，通常提供 LOGIN 或 PLAIN；更换密码不会增加认证机制

mailbox_worker_unreachable

code 为 mailbox_worker_unreachable 的 503 来自 DELETE /emails/{id}。断开邮箱前，必须先通知负责同步的机器，再删除记录，因为记录删除后就无法再通知该机器停止。指令无法投递时，不删除任何内容，邮箱完全保持原样。

{
  "error": "Service Unavailable",
  "message": "This mailbox could not be disconnected right now because the machine syncing it could not be reached. Nothing was removed, so try again in a moment.",
  "code": "mailbox_worker_unreachable",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

解决方法：

• 重试删除。可安全重复：邮箱已不存在时返回 404，仍存在时保持不变

mailbox_send_as_unsupported

code 为 mailbox_send_as_unsupported 的 400 来自 POST /emails/{id}/identity/refresh，以及设置 send_as_email 的 PATCH /emails/{id}。只有 Gmail 和 Google Workspace 邮箱会提供允许使用的发件地址列表；Outlook 或 SMTP/IMAP 邮箱没有此类列表，因此无内容可刷新，也无地址可选择。

{
  "error": "Bad Request",
  "message": "This mailbox's provider does not expose send-as addresses. Only Gmail and Google Workspace mailboxes do.",
  "code": "mailbox_send_as_unsupported",
  "request_id": "9f0a6f21-2c7e-4f2d-9d0e-1f7b9a2c4e55"
}

解决方法：

• 先读取 GET /emails/{id}/identity。这些邮箱的 supported 字段为 false，identities 为空
• 使用邮箱自身地址发送，即将 send_as_email 留空

mailbox_send_as_unknown

code 为 mailbox_send_as_unknown 的 400 来自将 send_as_email 设为服务商尚未为该邮箱验证的地址的 PATCH /emails/{id}。此处即拒绝选择，而非等到发送时；否则服务商可能几天后才针对营销活动步骤返回拒绝，且没有足以指导修复的信息。

{
  "error": "Bad Request",
  "message": "That address is not one your provider has verified this mailbox to send as. Refresh the list, or add and verify the address in your provider first.",
  "code": "mailbox_send_as_unknown",
  "request_id": "b71c3f88-0b3e-4a41-9a52-2f4f1fd0c0aa"
}

解决方法：

• 在 Gmail（设置、账户、“用这个地址发送邮件”）中添加别名并完成验证
• 调用 POST /emails/{id}/identity/refresh，让 Warmbly 重新读取列表，再将 send_as_email 设为 verified 为 true 的地址

mailbox_signature_too_large

code 为 mailbox_signature_too_large 的 400 来自设置了 import_signature 的 POST /emails/{id}/identity/refresh。服务商签名超过 Warmbly 存储上限（20000 个 HTML 字符），因此拒绝而非截断：不完整签名比没有签名更糟。发件地址列表也不会保存，因此调用不作任何更改。

{
  "error": "Bad Request",
  "message": "The signature on this mailbox is larger than Warmbly stores (20000 characters). Shorten it in your provider and import it again.",
  "code": "mailbox_signature_too_large",
  "request_id": "2d5e9a13-7c41-4f9b-bb17-a0f1d9c6e332"
}

解决方法：

• 在 Gmail 中缩短签名，通常可将内嵌图片改为图片链接，然后重新导入
• 或通过 PATCH /emails/{id} 直接在 Warmbly 中编写签名

mailbox_identity_unavailable

code 为 mailbox_identity_unavailable 的 503 来自 POST /emails/{id}/identity/refresh。读取邮箱发件地址属于账户操作，因此在持有该邮箱的工作节点上执行，而不由 API 自身执行。当该机器不可用时，此操作也不可用：例如邮箱正在工作节点间迁移、工作节点刚重启，或新连接邮箱尚未分配。未作任何更改。

{
  "error": "Service Unavailable",
  "message": "Warmbly could not reach the machine running this mailbox, so its sending addresses were not refreshed. Nothing was changed; try again in a moment.",
  "code": "mailbox_identity_unavailable",
  "request_id": "6e2f1a90-5d13-4a77-9c0b-73f0b5a2e118"
}

解决方法：

• 请重试。分配通常很快完成，第二次尝试往往成功
• GET /emails/{id} 报告邮箱的 status；inactive 邮箱根本不会分配到工作节点，在重新激活前会持续拒绝

错误处理最佳实践

实现重试逻辑

对于暂时性错误（5xx、429），请实现指数退避：

async function requestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.ok) {
        return response.json();
      }

      // Don't retry client errors (4xx) except rate limits
      if (response.status >= 400 && response.status < 500 && response.status !== 429) {
        throw new Error(`Client error: ${response.status}`);
      }

      // Retry server errors and rate limits
      if (attempt < maxRetries - 1) {
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
    }
  }
}

解析错误响应

始终解析并处理错误响应：

async function apiRequest(url, options) {
  const response = await fetch(url, options);

  if (!response.ok) {
    const error = await response.json();
    throw new ApiError(response.status, error.error, error.message);
  }

  return response.json();
}

class ApiError extends Error {
  constructor(status, type, message) {
    super(message);
    this.status = status;
    this.type = type;
  }
}

速率限制

超过速率限制时，您将收到：

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 60 seconds.",
  "code": "rate_limit_exceeded",
  "request_id": "4bbbd1b2-8f86-47dd-8a7f-9476501ad20e"
}

使用 Retry-After 响应头确定重试时间。

管理员设备请求错误

管理员设备流程 新增 admin_device_expired（404，无法区分无效、未知、过期或已消费请求）、admin_device_resolved（409，已作决定，或同意不匹配/被重放）及 admin_device_slow_down（429，轮询间隔短于五秒）。过期后重新开始，冲突时绝不自动批准。尝试额度采用现有 rate_limit_exceeded。身份验证/MFA/重新验证及依赖失败保留现有错误码。Redis 失败绝不会授权单因素或匿名管理员。节点诊断 使用通用错误及显式不可用/过时覆盖状态，而不是推断故障。

另请参阅

• 身份验证
• 端点