从这里开始

错误与重试

解析标准的 JSON 错误封装,并判断何时可以安全重试。

错误封装

JSON API 的失败响应统一使用一个顶层 error 对象,其中包含人类可读的 message、数字形式的 HTTP status,以及可选的稳定 code。OpenAPI 接口约定在预期和意外的失败中都引用这一 schema。

错误响应
{
  "error": {
    "code": "invalid_request",
    "message": "A verified From domain is required",
    "status": 403
  }
}

客户端错误

遇到 400 输入错误时,请先修正再重试。收到 401 后,请替换或吊销无效凭据。402 表示需要付费权益,403 表示触及策略或权限边界,404 表示租户范围内的资源不存在,409 表示状态或幂等冲突,413 表示超出附件限制,422 涵盖校验失败或抑制拦截。

重试决策

Do not automatically retry authentication, validation, suppression, conflict, or 402 subscription_required failures. A 402 means the workspace has no active subscription; choose a plan, then send. A 423 with code sender_paused means the exact From identity is paused. A 423 with code account_paused means the workspace is paused for review: the body includes the measured bounce and complaint rates and the limits they crossed (bounce_rate vs bounce_limit, complaint_rate vs complaint_limit). Stop that stream. A 429 with code daily_limit_reached is the workspace daily ladder, not a short backoff. Wait until resets_at (midnight UTC). Retry-After is the seconds until then. hourly_limit_reached waits until the next UTC hour. gmail_recipient_limit waits until midnight UTC. The refused message was not queued. Other 429 responses (quota_exhausted) wait until that monthly, per-sender, or attachment limit resets. A caller may retry a transient 502 or 503 with bounded exponential backoff and jitter. Preserve the same Idempotency-Key and identical JSON payload when retrying one logical send.

支持所需信息

请记录请求时间、路由、HTTP 状态码、SendHQ 资源 ID 以及不含机密信息的错误字段。支持工单中切勿包含 API 密钥、会话 Cookie、邮件正文或收件人列表。