可靠 API 重试与 Webhook 投递：从 429 到幂等证据

定义结果与责任人

本指南的可衡量目标是：设计客户端：计算 429/503 的安全重试时间、无幂等键时阻止自动重试 POST，并从投递日志核对每个 Webhook 事件的最终状态。

输入数据前先明确决策责任人、错误结果影响、停止条件与不得自动化的最终批准。不要把“运行成功”当标准，应设定用户任务、准确性、时间、可逆性与可解释性阈值。

• 设计客户端：计算 429/503 的安全重试时间、无幂等键时阻止自动重试 POST，并从投递日志核对每个 Webhook 事件的最终状态。

准备输入契约

在配置中明确安全/幂等方法、最大次数、总时长上限、Retry-After 优先级与抖动范围。每次投递记录稳定事件 ID、尝试次数、UTC 时间、状态与延迟，但不记录正文或密钥。

仅从合成、自有或重用权明确的数据开始。分别记录字段、类型、单位、语言、时区、敏感级别、缺失值与重复规则，并把原始输入保存为只读样本。

用小步骤构建正常路径

把 retry-after-geri-cekilme-planlayici、webhook-teslim-gunlugu-analizoru、http-durum-kodu-rehberi、api-sayfalama-planlayici 排列为输入验证、转换、结果复核与交付门槛，而不是一个不透明大操作。每个门槛都应有预期输出、失败消息、继续规则与责任人。

先用一条记录或小样本测试。在把结果与来源核对、并把假设显示在结果旁之前，不要扩展到大文件、自动发布或真实个人数据。

主动测试失败路径

常见故障包括重试所有 4xx、忽略 Retry-After、重复处理同一事件以及把耗尽重试视为成功。时钟偏差、乱序、部分中断、重复 2xx 与迟到的 200 都应单独做负面测试。

把空、损坏、超大、重复、乱序、跨语言与故意矛盾输入保留为负面测试。错误必须指出字段、原因与修正动作，不能静默修复。

验证用户与系统影响

在键盘操作、移动断点与受限设备上验证完整用户任务。核对来源与结果的数量、总计、标识、缺失值与变化字段。

视觉整洁不等于正确。重要主张应关联第一手证据，安全影响关联威胁模型，内容影响关联真实读者任务，性能影响关联浏览器测量。

记录发布证据

验收证据应包含每个事件仅一次业务影响、允许尝试次数、最终状态、首次成功时间、重复率与运维告警。区分合成事件与生产记录，并按事件 ID 核对幂等存储。

记录日期、工具与数据版本、验收阈值、负面测试、结果摘要、已知风险、人工批准与回滚步骤。单独截图不具可重复性；应同时保留配置与样本。

说明边界与下次复核

本地规划器不验证真实网络、队列、签名、TLS 或服务器时钟；可靠性必须通过受控集成与故障注入测试证明。

让边界与结果同样醒目，并设定下次复核日期。涉及法律、安全、健康或财务影响时，应把合格专家依据最新一手来源的复核设为强制发布门槛。

• 本地规划器不验证真实网络、队列、签名、TLS 或服务器时钟；可靠性必须通过受控集成与故障注入测试证明。