错误码全表

排障

所有错误响应统一为 { ok: false, error, message }；部分错误附带定位字段。请按 error 码（而非 message 文案）编写分支逻辑。

HTTP	error 码	含义与处理
401	api_key_required	未携带 Authorization 头。补上 Bearer 密钥。
401	invalid_api_key	密钥无效或已吊销。检查密钥或重新创建。
401	unauthorized	会话家族（developer/shared-index）缺少有效登录令牌。
403	insufficient_scope	密钥作用域不足。响应体列出 required / missing。
403	email_not_verified	开发者家族要求邮箱已验证。
404	api_not_found	路径不属于任何开放家族（入口层）。检查 URL 拼写。
404	endpoint_not_found	家族内路径未定义。
404	unknown_webhook_action	Webhook 动作不在 enable/disable/secret 之内。
404	plugin_version_not_found	按 plugin_key + version 找不到插件记录。
405	method_not_allowed	路径存在但方法不对。参见端点表。
409	idempotency_conflict	同一 Idempotency-Key 绑定了不同请求体。换 Key 或改请求体。
409	idempotency_in_progress	同一 Key 的首次请求仍在处理。稍后重试。
422	events_required	创建 Webhook 未指定 events。
422	unknown_events	events 含未知类型，响应体列出 allowed。
422	limit_invalid	limit 不是正整数。
422	limit_out_of_range	limit 超过上限 200。
422	plugin_key_and_version_required	验签缺少 plugin_key 或 version。
422	sha256_unavailable	既未提供 sha256 也无法回查到。
429	rate_limited	超出配额。按 retry_after 退避重试。
500	v1_error / shared_index_error	未预期异常。可重试一次；持续出现请报支持。
502	*_unavailable	上游数据源暂时不可用（如 favorites_unavailable）。稍后重试。
502	webhook_upstream_failed	Webhook 操作未产出响应。稍后重试。
503	not_configured	服务端凭据未配置（部署异常，重试无意义）。

错误响应长什么样

三种典型形态：入口层拒绝、作用域不足、配额耗尽。

# ① 入口层：路径不属于任何开放家族
HTTP/1.1 404
{ "ok": false, "error": "api_not_found",
  "url": "/api/zzz/x", "segs": ["zzz", "x"] }

# ② 作用域不足（响应体自带排查所需的三份清单）
HTTP/1.1 403
{ "ok": false, "error": "insufficient_scope",
  "message": "This API key does not carry the scope required by this endpoint",
  "required": ["read:orders"],
  "missing":  ["read:orders"],
  "declared": ["read:favorites"] }

# ③ 配额耗尽
HTTP/1.1 429
{ "ok": false, "error": "rate_limited",
  "scope": "apikey", "limit": 60,
  "window_seconds": 60, "retry_after": 23 }