外观
错误、重试与排查
错误响应
业务异常返回非 2xx HTTP 状态和以下 JSON:
json
{
"code": "FREQUENCY_CAPPED",
"message": "This placement is cooling down",
"requestId": "0b11e05e-381d-4720-9bf3-4b180d6fafb7"
}1
2
3
4
5
2
3
4
5
| 字段 | 类型 | 用法 |
|---|---|---|
code | string | 稳定的程序判断依据 |
message | string | 便于开发排查;不要把文案当作协议,也不要未经处理直接展示内部英文给用户 |
requestId | string | 与服务端日志关联;请求通常也有 X-Request-Id 响应头 |
反向代理、网络网关、JSON 解析/大小限制等较早阶段的错误不保证都具有这个结构。调用方应先判断 HTTP 状态,再尝试解析 JSON,并为 HTML/纯文本/空响应提供兜底。网络超时没有明确业务错误码,不能据此判断操作一定失败。
客户端与业务后端错误码
| HTTP | code | 触发条件 | 建议处理 |
|---|---|---|---|
| 400 | INVALID_INPUT | 字段缺失、类型/范围错误、严格请求体含未知字段;非法 status 筛选 | 修正参数;不要原样无限重试 |
| 400 | IDEMPOTENCY_REQUIRED | 创建会话缺少幂等键,或键超过 128 字符 | 生成并保存本次操作的 UUID 等随机键,再发送 |
| 400 | INTENT_INVALID | 意图不存在、已过期、应用/用户/广告位不匹配 | 由业务后端核对业务操作;不能由客户端擅自换用户或伪造意图 |
| 400 | INVALID_CURSOR | 客户端历史游标无效/过期/身份不匹配,或服务端同步游标格式无效 | 使用本接口返回的游标;客户端历史游标 7 天过期后从第一页恢复 |
| 400 | CURSOR_SCOPE_MISMATCH | 服务端 v2 游标的应用或 status 与当前请求不符 | 不同应用、筛选条件使用独立检查点 |
| 400 | INVALID_EVENT_TIMING | elapsedSeconds 超过服务端从 start 到首次接收事件的经过时间 | 修正单调计时来源;重试不能改写已生成事件 |
| 400 | INVALID_EVENT_TIMELINE | 显式 elapsedSeconds 随 sequence 倒退,跨缺口也检查 | 恢复同一会话单调时钟和原队列;1 毫秒容差不能累计漂移,整批未写入 |
| 401 | UNAUTHORIZED | 客户端 Token 缺失/过期/错误;X-App-Key 缺失/错误;应用暂停后使用服务端密钥 | Token 到期重新认证一次;密钥错误核对部署与轮换,不向客户端下发密钥 |
| 403 | APP_UNAVAILABLE | 已有 Token 调用配置、创建或启动时应用暂停/不存在 | 停止新展示,通知运营检查 |
| 403 | SERVER_IDENTITY_REQUIRED | server_pull/server_webhook 使用匿名入口或匿名 Token;匿名用户携带意图 | 切换为业务后端签发的客户端 Token |
| 403 | DELIVERY_MODE_MISMATCH | claim 用于非 client_claim;consume 用于非 server_pull | 按奖励自身 deliveryMode 执行正确交付流程 |
| 403 | REWARD_INTENT_REQUIRED | 广告位要求业务意图,但创建会话未提供 | 由业务后端验证业务权限并创建意图后再发起 |
| 404 | APP_UNAVAILABLE | 匿名入口使用的公开 appId 不存在或应用未启用 | 检查公开 appId、环境与应用状态 |
| 404 | PLACEMENT_UNAVAILABLE | 广告位不存在/暂停;意图指向非激励广告位 | 检查 placementCode 与配置;不要传内部 placementId |
| 404 | NO_FILL | 没有符合排期、状态、素材、视频阈值、投放额度等要求的广告 | 向用户表示暂时没有广告,稍后再试;不是系统崩溃 |
| 404 | NOT_FOUND | 会话/奖励不存在,或不属于当前应用/用户;ack 的 grantId 不匹配;reported-applied 条件不符 | 核对 ID、Token 用户、应用;不要把 404 当作可跨用户读取的提示 |
| 409 | IDEMPOTENCY_CONFLICT | 同一创建 key 的请求体改变;同一 businessKey 的用户或广告位改变 | 恢复原参数重试;只有新的真实业务操作才能使用新 key |
| 409 | SESSION_ACTIVE | 用户在该应用已有活动会话 | 恢复已保存会话,完成或关闭后再创建 |
| 409 | SESSION_EXPIRED | start 时未启动会话过期/已结束;events 超过证据截止时间 | 查询状态和奖励;需要新广告时使用新创建 key |
| 409 | SESSION_NOT_STARTED | start 前上报 heartbeat、complete 或 click | 先 start;只有全为 close 的批次允许在启动前关闭 |
| 409 | AD_UNAVAILABLE | 创建后、start 前广告位/投放/素材失效或排期结束 | 关闭旧会话,重新请求可用广告 |
| 409 | INTENT_USED | 意图已经绑定其他会话 | 恢复原会话;新业务机会需由后端明确批准 |
| 409 | EVENT_CONFLICT | 已存在 eventId 或 sequence,但任一事件字段不同 | 恢复原始事件,禁止复用序号或修改重试内容;整批拒绝 |
| 409 | INVALID_PLACEMENT | 不兼容的广告位意图配置,例如非激励广告要求意图 | 管理后台修正配置;正常后台会阻止此组合 |
| 409 | REWARD_PENDING | claim/consume 时 eligibility 不是 ELIGIBLE | 查会话和奖励状态;也可能是 REJECTED,不能无条件一直轮询 |
| 409 | REWARD_EXPIRED | 超过 24 小时后首次 claim/consume | 进入业务补偿流程;直接重试不会延长期限 |
| 409 | INVALID_STATE | client_claim 调用 acknowledge,或尚未 consume/排队就确认 | 先完成对应流程;只在业务资产事务提交后确认 |
| 409 | CONFLICT | 底层唯一约束冲突,例如并发创建同一业务意图 | 对确实相同的幂等操作退避重试一次;不同参数需要修正 |
| 429 | FREQUENCY_CAPPED | 用户日额度、广告位冷却或并发预占后的额度不足 | 停止紧密轮询,等待冷却/次日或运营配置调整 |
| 429 | RATE_LIMITED | 来源 IP 的进程级请求频率超限 | 指数退避并减少并发;当前无 Retry-After |
| 429 | EVENT_LIMIT_EXCEEDED | 单个会话已保存 2048 条事件,新增会超限 | 停止追加;查询现状与奖励,不要通过换 key 伪造同次观看 |
| 500 | INTERNAL_ERROR | 未分类服务端异常 | 保存 requestId;对幂等操作有界重试,持续失败交由运维排查 |
| 其他 | HTTP_<status> | 框架 HttpException 未提供业务 code | 保留状态、响应内容与 requestId,采用通用错误兜底 |
媒体加载还可能返回 404 MEDIA_NOT_FOUND 或 404 MEDIA_NOT_PUBLISHED。媒体加载失败不能视为观看达标;页面应提供关闭和重试入口。
按场景恢复
创建广告请求超时
保持同一 Idempotency-Key、同一用户 Token 身份、同一请求体再次创建。若服务端已经创建,会返回原来的会话;若没有创建,会执行创建。不要为了“重试”立刻换 key,否则原会话可能还占用活动位置。
已成功保存会话 ID 后,也可 GET /client/ad-sessions/:id 恢复。旧 key 总是指向旧会话,过期后重用旧 key不会生成新广告。
事件上报失败
保留原 eventId、sequence、visibleSeconds、positionSeconds 和 elapsedSeconds,重试原始事件。服务端保存乱序事件并重放从 1 开始的连续前缀;lastSequence 未推进时检查是否缺少更小序号。相同 ID/序号但改写内容会返回 EVENT_CONFLICT。建议串行持久化队列,发送成功后再移除已确认批次。
超过 showDeadline 仍可在 evidenceDeadline 前补交带 elapsedSeconds、声明发生在展示窗口内且通过校验的证据;不带 elapsedSeconds 的旧事件只按首次接收时间保守判定。close 乱序先到不会直接丢弃它之前的合法证据,close 后发生的观看不算有效。超过 evidenceDeadline 拒绝新事件,完全一致的已有事件重试仍可返回当前状态。最终以服务端资格为准,不承诺离线一定发奖。
claim 或 consume 响应丢失
用原奖励 ID 重试。已经领取的操作返回原 grantId,首次领取的 24 小时期限不会阻止已完成领取的幂等恢复。APP 本地或业务数据库仍要用 grantId 去重,不能因重复成功响应重复增加资产。
业务资产已到账,acknowledge 失败
保留本地已入账记录和待确认任务,重复 acknowledge。不要回滚已经入账的奖励来迎合网络状态,也不要重新增加资产。重复确认同一 rewardId/grantId 会返回同一奖励。
Webhook 超时、重复或停发
接收方先验签,再查/写自己的 grantId 唯一记录,已发放仍返回 2xx + { grantId, status: "fulfilled" }。自动重试耗尽后由管理后台查看失败原因并手动重试;错误 HTML、空 204 或只返回 { "ok": true } 都不算合格确认。详见 Webhook。
推荐调用器策略
- 对每次 HTTP 请求设置有限超时,错误日志记录路径、HTTP 状态、code、requestId 和非敏感业务 ID。
- 对网络错误、502/503/504 和暂时性 500 做有上限的退避重试;保护原有幂等键。
- 401 最多触发一次重新获取客户端 Token;避免重复登录循环。业务后端 401 应检查密钥和应用状态。
NO_FILL、FREQUENCY_CAPPED、业务参数错误使用对应 UI 提示;不要按故障重试风暴处理。- 不在日志中记录完整客户端 JWT、X-App-Key、Webhook 验签密钥或管理登录 Cookie。
系统不会返回“下一次必定有广告”的时间,也没有取消奖励、强制改资格、客户端强制发奖等公开接口。需要业务补偿时,应在自己的后端留下独立审计记录。