本文为原文前 6,000 字符的节选翻译，完整内容请查看原文。

Marketplace Email API 429 Rate Limit Errors: Handling Queue-Owned Contact Routing

Short answer: treat an email API 429 as delayed work, not a failed contact form. Keep the marketplace queue, template version, and message ID unchanged; honor Retry-After; then retry from a durable worker with capped exponential backoff, jitter, and an explicit age limit. The useful boundary is ownership. The team that owns the support template should define how long that message class may wait and what happens when it expires. Shared infrastructure should enforce the transport rules. That arrangement makes a seller payout question different from a general product question without duplicating the retry machinery. This is a queueing problem before it is an HTTP problem.

简短的回答是：将电子邮件 API 429 错误视为延迟任务，而不是联系表单提交失败。保持市场队列、模板版本和消息 ID 不变；遵循 Retry-After 指令；然后通过具有上限指数退避、抖动和明确有效期限制的持久化工作进程进行重试。有效的边界在于所有权。支持模板的所有者团队应定义该类消息可以等待多长时间以及过期后的处理方式。共享基础设施应强制执行传输规则。这种安排使得卖家付款问题与一般产品问题有所区别，且无需重复构建重试机制。这首先是一个排队问题，其次才是 HTTP 问题。

How should Node.js handle email API 429 rate limit errors? The request path should validate the form, assign a support queue, render the approved template, and enqueue a delivery job. A worker then calls the email API. When the API returns 429, the worker schedules that same job for later instead of making the browser submit the form again. In the routing record, preserve a correlation ID, message ID, queue, template owner, template version, rendered payload, attempt count, and creation time. The payload should be immutable after enqueueing. A template edit made while a job is delayed should not silently change the promised reply.

Node.js 应如何处理电子邮件 API 429 限流错误？请求路径应验证表单、分配支持队列、渲染已批准的模板并加入投递任务队列。随后，工作进程调用电子邮件 API。当 API 返回 429 时，工作进程应将同一任务安排在稍后执行，而不是让浏览器重新提交表单。在路由记录中，应保留关联 ID、消息 ID、队列、模板所有者、模板版本、渲染后的有效载荷、尝试次数和创建时间。有效载荷在入队后应保持不可变。在任务延迟期间对模板进行的编辑不应静默更改已承诺的回复。

The response status has a precise meaning: the service is asking the client to slow down. RFC 6585 defines 429, and Retry-After can express either a number of seconds or an HTTP date. Neither fact supplies an unlimited retry budget. The worker still needs a maximum age, an attempt boundary, and a dead-letter path. SPF is relevant to sender authorization, but it does not increase an API’s request allowance. Authentication, reputation, and throttling belong to related but separate parts of deliverability.

响应状态具有明确含义：服务正在要求客户端降低速度。RFC 6585 定义了 429 状态码，Retry-After 可以表示秒数或 HTTP 日期。但这并不意味着拥有无限的重试预算。工作进程仍然需要最大有效期、尝试次数限制和死信路径。SPF 与发件人授权有关，但它不会增加 API 的请求配额。身份验证、信誉和限流属于可投递性中相关但独立的组成部分。

A retry policy that keeps ownership intact Put the policy in a transport-independent module. In a Node.js service, the queue library and HTTP client will be JavaScript; the decisions below are deliberately shown as plain Python because the state transitions are easier to inspect in an eval harness. The same inputs should produce the same class of outcome in either implementation.

保持所有权完整的重试策略：将策略置于与传输无关的模块中。在 Node.js 服务中，队列库和 HTTP 客户端将使用 JavaScript；下方的决策特意以纯 Python 展示，因为在评估工具中更容易检查状态转换。在任何一种实现中，相同的输入都应产生相同类别的结果。

from dataclasses import dataclass
from datetime import datetime, timezone
import email.utils
import random

@dataclass
class DeliveryJob:
    message_id: str
    queue: str
    template_owner: str
    template_version: str
    attempt: int = 0

def retry_delay(headers: dict[str, str], attempt: int, now: datetime) -> float:
    value = headers.get("retry-after")
    if value:
        try:
            return max(0.0, float(value))
        except ValueError:
            try:
                retry_at = email.utils.parsedate_to_datetime(value)
                if retry_at.tzinfo is None:
                    retry_at = retry_at.replace(tzinfo=timezone.utc)
                return max(0.0, (retry_at - now).total_seconds())
            except (TypeError, ValueError, OverflowError):
                pass
    # The cap limits queue age; jitter stops workers sharing one wake-up time.
    base = min(300.0, 2 ** min(attempt, 8))
    return base * random.uniform(0.5, 1.0)

def decide(job: DeliveryJob, status: int, headers: dict[str, str], now: datetime):
    if status in (200, 201, 202):
        return ("completed", 0.0)
    if status == 429 and job.attempt < 8:
        return ("retry", retry_delay(headers, job.attempt, now))
    return ("dead_letter", 0.0)

The five-minute value and eight-attempt boundary are policy examples, not universal truths. A queue owner should choose them against the maximum acceptable delivery age. They must be visible configuration, covered by tests, and included in the runbook. A fixed sleep is tempting because it is short. It also makes a fleet wake up together, recreate the burst, and receive another 429. Jitter trades exact timing for a less synchronized load pattern.

五分钟的数值和八次尝试的边界只是策略示例，而非普遍真理。队列所有者应根据最大可接受投递时效来选择这些参数。它们必须是可见的配置，并由测试覆盖且包含在运行手册中。固定的休眠时间虽然简短且诱人，但会导致整个集群同时唤醒、重现流量突发并再次收到 429 错误。抖动（Jitter）通过牺牲精确的时间控制，换取了负载模式的非同步化。

In production, the worker should acknowledge the queue only after it has recorded the provider outcome. If the provider supports an idempotency key, derive it from the stable message ID rather than generating one for every attempt. If a timeout occurs after the request may have been accepted, local code cannot prove that no email exists. Mark the outcome as unknown and send it through reconciliation; do not blindly create a fresh logical message. Do not retry the form submission itself.

在生产环境中，工作进程应仅在记录了服务商的处理结果后才确认队列任务。如果服务商支持幂等键，应从稳定的消息 ID 中派生，而不是为每次尝试生成一个新的。如果请求可能已被接受但发生了超时，本地代码无法证明邮件不存在。应将结果标记为未知并进行对账；不要盲目创建新的逻辑消息。不要重试表单提交本身。

This design is a poor fit for a synchronous, low-volume script that has no durable queue and no replay operator. In that case, adding a queue introduces state and maintenance work that may exceed the value of delayed delivery. The trade-off is deliberate: durable scheduling improves recovery and auditability, while it also requires ownership for dead letters, retention, and reconciliation.

这种设计不适合没有持久化队列和重放操作的同步、低流量脚本。在这种情况下，引入队列会带来状态管理和维护工作，其成本可能超过延迟投递带来的价值。这种权衡是经过深思熟虑的：持久化调度提高了恢复能力和可审计性，同时也要求对死信、保留策略和对账承担所有权责任。

Who owns the template and who owns the retry? Template ownership should live in the routing record, but transport behavior should live in shared infrastructure. The template owner controls recipients, required fields, language variants, version retention, and the acceptable age for that message class. The platform layer controls rate-limit accounting, delay scheduling, idempotency, metrics, and redaction. That split prevents a common operational mismatch: a generic helper applies one delay to every message while queue owners assume urgent cases have priority.

谁拥有模板，谁拥有重试机制？模板所有权应存在于路由记录中，而传输行为应存在于共享基础设施中。模板所有者控制收件人、必填字段、语言变体、版本保留以及该类消息的可接受时效。平台层控制限流统计、延迟调度、幂等性、指标和脱敏。这种拆分防止了常见的操作失误：通用辅助程序对每条消息应用相同的延迟，而队列所有者却认为紧急情况应具有优先权。

A buyer-safety report may need a shorter age budget than a low-priority seller question. The worker can support both with named policies such as urgent_safety and standard_support; it should not execute arbitrary policy code stored in a form field. The route must remain stable during a retry. If the job changes from seller_support to billing merely because its first delivery was throttled, the system has transformed a transport event into a business decision. Those are different events and deserve different audit records.

买家安全报告可能比低优先级的卖家问题需要更短的时效预算。工作进程可以通过命名策略（如 urgent_safety 和 standard_support）同时支持两者；它不应执行存储在表单字段中的任意策略代码。路由在重试期间必须保持稳定。如果任务仅仅因为第一次投递被限流就从“卖家支持”变更为“账单”，系统就将传输事件转化为了业务决策。这些是不同的事件，应有不同的审计记录。

How do you test recovery instead of trusting it? An eval harness should feed the policy a sequence containing a success, a 429 with seconds, a 429 with an HTTP date, a malformed header, a missing header, a timeout after possible acceptance, and a permanent 4xx. Assertions should cover more than a final state.

如何测试恢复能力而不是盲目信任它？评估工具应向策略输入一个序列，包含成功响应、带秒数的 429、带 HTTP 日期的 429、格式错误的标头、缺失的标头、可能被接受后的超时以及永久性的 4xx 错误。断言应涵盖最终状态之外的更多内容。