API 错误 — 每个代码的含义及修复方法

当请求失败时，FastOG 会返回机器可读的错误代码 — 无论是签名 OG 图片渲染，还是对产品内某个管理界面的调用。每个错误响应都包含：

• error — 旧版短令牌。每次失败时仍然存在，以便旧版客户端继续正常工作。
• code — 相同的稳定、有文档记录的错误代码（见下表），使用公共 API 所用的名称。
• message — 一句话描述出错的原因。
• hint — 用通俗语言简短描述出错的原因以及如何修复。
• docs_url — 指向本页面的链接，锚定到该代码对应的章节。
• request_id — 将此 HTTP 失败关联到仪表盘 Render Logs 表中的一行（同时也会在 X-Request-ID 响应头中返回）。没有可关联内容的界面会返回 null，但该键始终存在。

产品内界面 — Shopify 管理后台、WooCommerce Studio、Wix 桥接和演示 — 对以下代码返回相同的响应信封，因此无论你在哪里遇到失败，其含义都相同。模块界面可能会保留某个代码一直以来的 HTTP 状态（例如 render_failed 在封面导出时返回 503，在公共 API 上返回 502）；代码、消息、提示和文档链接不会改变。

读取错误响应

{
  "error": "invalid_signature",
  "code": "invalid_signature",
  "message": "The signature does not match.",
  "hint": "The signature did not match. Re-sign with your HMAC secret after every param change.",
  "request_id": "5f2a9c1e-..."
}

如果收到无法理解的响应，最快的排查路径是：

1. 记下 code。
2. 检查你的 URL 构建逻辑——大多数失败都是签名错误，而不是账户问题。
3. 对照下面的错误码找到确切原因和修复方法。
4. 在仪表盘中打开 Render Logs，按相同的 error_code 过滤——每一行都会显示请求的参数，方便你复现（并确认 request_id 是否匹配）。

签名与身份验证

missing_signature

您的请求缺少 key 和/或 s（签名）查询参数。

修复： 请确保您的 URL 同时包含 key=<api-key> 和 s=<hmac-signature>。请使用 SDK 或 /docs/hmac-signature-guide 演练来构建它。

invalid_signature

s 的值与您的 HMAC 密钥为此 URL 生成的值不匹配。

修复： 签名覆盖 所有 查询参数（s 除外），且键已排序。更改任何参数——包括重新排序、URL 编码差异或添加空白——都会使签名失效。每次更改后请重新签名。请确认您的密钥与创建 API 密钥时显示的密钥相同。

invalid_signature_format

s 的值不是 64 个字符的十六进制字符串。

修复： 签名必须是原始 SHA-256 十六进制（小写 a-f0-9）。如果您对输出进行了 base64 编码或截断，请改用纯十六进制。

expired_timestamp

您提供的 t 时间戳已超过 5 分钟。

修复： 每次构建 URL 时请重新生成时间戳。此代码适用于旧版签名 URL 流程；当前的 HMAC v2 流程没有时间戳。

invalid_api_key

您传入的 key 不存在。

修复： 请从仪表板复制完整的 API 密钥——它是以 sk_ 开头的公开标识符。它是公开的，在 URL 中使用是安全的；密钥（绝不要放在 URL 中）才是证明所有权的凭据。

missing_hmac_secret

该 API 密钥未配置 HMAC 密钥。

修复： 请在仪表板中创建新的 API 密钥——HMAC 密钥会在创建时生成并仅显示一次。

参数 / 输入

invalid_image_url

带有 URL 的 prop（image、brand_logo、logo、avatar、background_image、...）不是公开的 http(s) URL。

修复： 请传入可公开访问的 https://... URL。为防止服务端请求伪造，localhost、私有 IP 和裸路径都会被拒绝。

订阅

subscription_required (402)

请求已到达 Dynamic API，但您的账户没有生效中的套餐。API 访问仅限订阅用户：套餐是准入门槛，并且提供与 FastOG 应用所售相同的覆盖范围与能力阶梯。渲染本身不计费——没有每月渲染配额，也没有超额计费。

修复： 请在仪表盘中选择一个 Dynamic API 套餐并创建 API 密钥。响应中包含一个指向套餐页面的 top_up_url。

渲染服务

store_blocked (403)

该密钥所对应店铺的渲染已被 FastOG 暂停（例如滥用或用量失控）。已缓存在边缘的封面图可能继续提供服务，直至过期。请联系支持团队解决；在请求中做任何更改都无法修复此问题。

render_unreachable

无法访问渲染服务（短暂重启窗口）。

修复： 请在几秒后重试。本次尝试未计入渲染次数。

render_failed

渲染服务为您的请求返回了错误。

修复： 请检查您的模板 props——过长/格式错误的值、不支持的字段，或无法访问的上游图片。响应中包含底层的 status。本次渲染未计入次数。

商店管理后台界面

这些代码从 Shopify 管理后台和 WooCommerce Studio 返回响应——即商家实际使用的嵌入式编辑器，而非已签名的 API。其中若干与公共 API 共用（invalid_image_url、render_failed、invalid_signature）；这些代码保留上文记录的条目。

Wix 桥接

Wix 桥接由 Wix 应用签名，而非商家会话，因此其失败信息面向应用开发者。每个响应仍携带 code 和 request_id；桥接请求 id 来自签名信封中的那个。

演示界面

该演示是仅限所有者使用的销售控制台，不是商户端点。

作用域规则编辑器代码

作用域规则编辑器（Shopify 管理后台和 WooCommerce Studio）会自行将这些令牌翻译成商家自己的语言，因此它们的响应会带有 error 和 code，但不带 hint——第二份英文描述只会与商家实际看到的本地化描述产生偏差：

scope_already_defined、scoped_rule_limit_reached、scoped_rules_not_on_plan、 scope_value_required、scope_value_too_long、unknown_scope_type、base_rule_required、 scoped_rules_product_only、cannot_delete_base_rule。

仍然无法解决？

• 请打开 dashboard 的 Render Logs 页面——每个结果（成功和拒绝）都会列出其 error_code、HTTP 状态码以及请求的参数。
• 请对已签名的 URL 运行 php artisan og:diagnose，以走完整个流水线并查看哪个阶段失败。
• 请查看侧边栏中你所使用框架的文档（Next.js、Express、SvelteKit 等）。