错误契约

统一约定：成功响应是 image/*，失败响应一律是 application/json。 调用方只需判断 Content-Type 即可知道成败，不必解析图片字节。

错误响应体

所有非 2xx 响应的 body 结构一致：

{
  "ok": false,
  "error": {
    "code": "invalid_params",   // ErrorCode
    "field": "width",           // 仅 invalid_params 时提供：出错的参数名
    "message": "width must be between 200 and 2400"
  }
}

错误码

code	HTTP	触发条件
invalid_params	400	参数缺失、类型错误、越界、枚举非法（含 field）
template_not_found	404	template 不在注册表里
not_found	404	路由不存在（非 /og、/templates、/fonts、/healthz）
render_failed	500	渲染阶段抛错（satori / 字体 / 底版问题）

示例

# 非法 width → 400
curl -s "https://og.159499.xyz/og?width=3000" | head -c 200
# {"ok":false,"error":{"code":"invalid_params","field":"width","message":"width must be between 200 and 2400"}}

# 未知模板 → 404
curl -s "https://og.159499.xyz/og/does-not-exist" | head -c 200
# {"ok":false,"error":{"code":"template_not_found","message":"unknown template: does-not-exist"}}

# 非法枚举 format → 400
curl -s "https://og.159499.xyz/og?format=gif" | head -c 200
# {"ok":false,"error":{"code":"invalid_params","field":"format","message":"format must be one of: svg, png"}}

客户端建议

1. 读 Content-Type：是 image/* 就当图片存；是 application/json 就解析 error。
2. 业务上区分 4xx（请求方问题，改参数重试）与 5xx（服务端问题，告警 + 退避）。
3. invalid_params 的 field 直接告诉你哪个参数错了，可用于高亮表单。