跳转到主要内容

​
错误结构

所有错误响应均为 JSON，Content-Type: application/json： 
{ "error": "brief_not_found" }
部分端点会包含额外字段： 
{
  "error": "invalid_request",
  "error_description": "iso2 must be a 2-letter uppercase country code",
  "field": "iso2"
}
OAuth 端点遵循 RFC 6749 §5.2 错误码：invalid_request、invalid_client、invalid_grant、unsupported_grant_type、invalid_scope。

​
状态码

状态码含义是否重试？
200OK—
202已接受 — 作业已入队。轮询以获取最终状态。—
304未修改（条件缓存命中）—
400错误请求 — 校验错误否 — 修正输入
401缺失 / 无效的认证否 — 修正认证
403已认证但无权限（通常为 pro_required）否 — 升级订阅
404资源 / 工具 / brief / 实体未找到否
405方法不允许否
409冲突（重复的 webhook 注册等）否
413请求体过大否
429触发速率限制是 — 遵守 Retry-After
500服务器 bug是 — 退避后重试，再上报
502上游 / Convex / Dodo 故障是 — 指数退避
503服务不可用 — 缺失环境变量或依赖不可用是 — 指数退避
504上游超时是 — 退避后重试

​
常见错误字符串

error 值含义
UNAUTHENTICATED无有效的 Clerk JWT 或 API 密钥。
pro_required已认证，但账户非 PRO。
invalid_payload请求体未通过 schema 校验。
invalid_date_shape日期参数非 YYYY-MM-DD。
brief_not_found所请求的 {userId, issueDate} 没有已生成的 brief。
Rate limit exceeded触发 429；遵守 Retry-After。
Service temporarily unavailableUpstash 或其他硬依赖在请求时不可用。
service_unavailable签名密钥 / 必需的环境变量未配置。
Failed to enqueue scenario job/api/scenario/v1/run-scenario 上的 Redis 管道故障。

​
重试策略

幂等读（GET）：对 429/5xx 使用指数退避重试（1 秒、2 秒、4 秒，上限 30 秒，共 5 次）。大多数 GET 响应在边缘已缓存，因此重试通常更快完成。 写入：切勿自动重试 4xx。对于写入时的 5xx，需甄别：POST /api/brief/share-url 与 POST /api/v2/shipping/webhooks 是幂等的；POST /api/scenario/v1/run-scenario 不幂等 — 每次调用都会入队一个新作业。对 run-scenario 重试 5xx 可能会使速率限制计数翻倍。 MCP：服务器在 JSON-RPC 结果中以 isError: true 和文本说明返回工具错误 — 这些并非 HTTP 错误。请在工具调用层进行处理。

​
调试

  • 每个 Edge 响应都包含 x-vercel-id 与 x-worldmonitor-deploy 头 — 上报问题时请一并提供。
  • Sentry 告警会转发到 status.worldmonitor.app。
  • GET /api/health 与 GET /api/seed-health 显示各 seed 的数据新鲜度；某个 seed 过期是出现意外空载荷的最常见根因。