title: Mailbox HTTP API 错误处理

Mailbox HTTP API 错误处理

这页汇总公开 HTTP API 的常见状态码和建议处理方式。

所有业务错误都通过统一 EnvelopMessage 返回，不再默认返回裸 ProblemDetails：

{
  "data": null,
  "code": 401,
  "msg": "Unauthorized",
  "errMsg": "Mailbox token is required.",
  "tid": "trace-id"
}

400 Bad Request

常见原因：

• mailboxAddress 不合法
• domain token 没带 mailboxAddress
• mailbox token 指定了其他邮箱的 mailboxAddress
• direction 不是 inbound 或 outbound
• limit 超出允许范围
• cursor 非法或无法解析
• 回复时 mailboxAddress 与父消息所属邮箱不一致
• 附件上传表单非法

建议：

• 检查请求体字段格式
• 检查 token 类型与 mailboxAddress 是否匹配
• 检查分页参数范围和格式
• 检查 cursor 是否来自上一次返回的 nextCursor

401 Unauthorized

常见原因：

• 没带 Authorization
• token 无效
• token 已过期
• token 已禁用

建议：

• 先确认请求头是否存在
• 再检查 token 生命周期

403 Forbidden

常见原因：

• scope 不足
• 例如没有 MailboxSend 却去发信
• 没有 AttachmentWrite 却上传附件
• 没有 TokenManage 却治理 token

建议：

• 检查当前 token 是否具备所需 scope

404 Not Found

常见原因：

• 消息不存在
• 线程不存在
• tokenId 不存在
• 当前 token 无权访问该对象

注意：

• 在这套 API 中，404 也可能表示“对象存在，但对当前 token 不可见”

409 Conflict

常见场景：

• 创建邮箱时邮箱已存在
• reveal token 明文时，该明文已不可用

建议：

• 先检查是否是重复创建
• 对 token 明文场景，必要时重新签发新 token

429 Too Many Requests

发信或回复触发邮箱级速率限制时会返回：

• 429 Too Many Requests
• Retry-After 响应头

建议：

• 读取 Retry-After
• 做退避重试
• 不要立即高频重放

平台特有语义

202 Accepted

适用于：

• POST /api/messages/send
• POST /api/messages/{messageId}/reply

含义：

• 请求已接收并入队
• 不代表远端邮箱已经签收

201 Created

适用于：

• 创建邮箱
• 上传附件
• 创建 token