APIエラー — 各コードの意味と修正方法

FastOGは、リクエストが失敗したとき — 署名付きOG画像のレンダリング、または製品内の管理画面のいずれかへの呼び出し — に機械可読なエラーコードを返します。すべてのエラーレスポンスには次のものが含まれます:

• error — 従来の短いトークンです。古いクライアントが引き続き動作するよう、すべての失敗時に今も含まれます。
• code — 同じ安定した文書化済みのエラーコード(下表)を、公開APIが使用する名前で示したものです。
• message — 何が問題だったかを1文で説明したものです。
• 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 のチュートリアルを使用して URL を構築してください。

invalid_signature

s の値が、この URL に対して HMAC シークレットが生成する値と一致しませんでした。

修正: 署名は s を除くすべてのクエリパラメータを対象とし、キーはソートされます。パラメータを変更すると (並び順の変更、URL エンコードの差異、空白の追加など)、署名は無効になります。変更のたびに再署名してください。シークレットが API キー作成時に表示されたものと同じであることを確認してください。

invalid_signature_format

s の値が 64 文字の 16 進文字列ではありません。

修正: 署名は生の SHA-256 16 進数 (小文字の a-f0-9) である必要があります。出力を base64 エンコードしたり切り詰めたりしている場合は、プレーンな 16 進数を使用してください。

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 を含むプロパティ（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。

まだ解決しませんか？

• ダッシュボードの Render Logs ページを開いてください。すべての結果（成功と拒否の両方）が error_code、HTTP ステータス、リクエストされたパラメータとともに一覧表示されます。
• 署名済み URL に対して php artisan og:diagnose を実行すると、パイプライン全体をたどってどの段階で失敗するかを確認できます。
• サイドバーのドキュメントで、使用しているフレームワーク（Next.js、Express、SvelteKit など）の項目を確認してください。