API 錯誤 — 每個代碼的意義與修正方式

當請求失敗時，FastOG 會回傳機器可讀的錯誤代碼 — 無論是簽章過的 OG 圖片算繪，或是對其中一個產品內管理介面的呼叫。每個錯誤回應都包含：

• error — 舊版的短 token。每次失敗時仍會保留，讓較舊的用戶端能繼續運作。
• 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. 在 dashboard 中開啟 Render Logs，並以相同的 error_code 篩選 — 每一列都會顯示請求的參數，讓您可以重現（並確認 request_id 相符）。

簽章與驗證

missing_signature

您的請求缺少 key 和/或 s（簽章）查詢參數。

修正方式： 請確認您的 URL 同時包含 key=<api-key> 與 s=<hmac-signature>。請使用 SDK 或參照 /docs/hmac-signature-guide 的逐步說明來建構 URL。

invalid_signature

s 的值與您的 HMAC 密鑰為此 URL 產生的結果不符。

修正方式： 簽章涵蓋所有查詢參數（s 除外），且鍵值需排序。變更任何參數——包括重新排序、URL 編碼差異或新增空白——都會使簽章失效。每次變更後請重新簽章。請確認您的密鑰與建立 API key 時顯示的密鑰相同。

invalid_signature_format

s 的值不是 64 字元的十六進位字串。

修正方式： 簽章必須是原始 SHA-256 十六進位（小寫 a-f0-9）。若您對輸出進行 base64 編碼或截斷，請改用純十六進位。

expired_timestamp

您提供的 t 時間戳已超過 5 分鐘。

修正方式： 每次建構 URL 時請重新產生時間戳。此代碼適用於舊版簽章 URL 流程；目前的 HMAC v2 流程沒有時間戳。

invalid_api_key

您傳入的 key 不存在。

修正方式： 請從 dashboard 複製完整的 API key——它是以 sk_ 開頭的公開識別碼。此識別碼是公開的，放在 URL 中是安全的；真正用來證明持有權的是密鑰（絕不可放在 URL 中）。

missing_hmac_secret

此 API key 未設定 HMAC 密鑰。

修正方式： 請在 dashboard 建立新的 API key——HMAC 密鑰會在建立時產生並僅顯示一次。

參數 / 輸入

invalid_image_url

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

修正方式： 請傳入可公開存取的 https://... URL。為了防止伺服器端請求偽造（server-side request forgery），localhost、私有 IP 與裸路徑都會被拒絕。

訂閱

subscription_required (402)

請求已送達 Dynamic API，但您的帳戶沒有啟用中的方案。API 存取僅限訂閱：方案是存取的門檻，並提供與 FastOG 應用程式所販售相同的涵蓋範圍與功能層級。轉譯本身不計量——沒有每月轉譯配額，也沒有超額計費。

修正方式： 請在儀表板中選擇 Dynamic API 方案並建立 API 金鑰。回應中會包含指向方案頁面的 top_up_url。

轉譯服務

store_blocked (403)

此金鑰所屬商店的轉譯功能已被 FastOG 暫停（例如濫用或用量失控）。已快取在邊緣的封面圖可能仍會繼續提供，直到過期為止。請聯絡支援團隊處理；你在請求中做的任何變更都無法解決此問題。

render_unreachable

無法連線至轉譯服務（短暫重啟期間）。

修正方式： 請於幾秒後重試。此次嘗試的轉譯未被計入。

render_failed

轉譯服務對你的請求回傳了錯誤。

修正方式： 請確認你的 template props — 過長或格式錯誤的值、不支援的欄位，或無法連線的 upstream 圖片。回應中會包含底層的 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……）的文件。