API Errors — What Each Code Means and How to Fix It

FastOG returns machine-readable error codes when a request fails — a signed OG image render, or a call to one of the in-product admin surfaces. Every error response includes:

• error — the legacy short token. Still present on every failure so an older client keeps working.
• code — the same stable, documented error code (table below), under the name the public API uses.
• message — a one-sentence description of what went wrong.
• hint — a short plain-language description of what went wrong and how to fix it.
• docs_url — a link to this page, anchored at the section for that code.
• request_id — correlates this HTTP failure to a row in the dashboard Render Logs table (also returned in the X-Request-ID response header). A surface with nothing to correlate answers null, but the key is always present.

The in-product surfaces — the Shopify admin, the WooCommerce Studio, the Wix bridge and the demo — answer with the same envelope for the codes below, so a failure means the same thing wherever you meet it. A module surface may keep the HTTP status it has always returned for a code (for example render_failed answers 503 on the cover export and 502 on the public API); the code, message, hint and docs link do not change.

Reading an error response

{
  "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-..."
}

If you get a response you don't understand, the fastest path is:

1. Note the code.
2. Check your URL builder — most failures are signing bugs, not account issues.
3. Match the code below for the exact cause and fix.
4. In the dashboard, open Render Logs and filter by the same error_code — each row shows the requested params so you can reproduce (and confirm request_id matches).

Signing & authentication

missing_signature

Your request is missing the key and/or s (signature) query parameters.

Fix: ensure your URL includes both key=<api-key> and s=<hmac-signature>. Use the SDK or the /docs/hmac-signature-guide walkthrough to build it.

invalid_signature

The s value did not match what your HMAC secret produces for this URL.

Fix: the signature covers every query param except s, with keys sorted. Changing any param — including reordering, URL-encoding differences, or adding whitespace — invalidates the signature. Re-sign after every change. Confirm your secret is the same one shown when the API key was created.

invalid_signature_format

The s value is not a 64-character hex string.

Fix: the signature must be raw SHA-256 hex (lowercase a-f0-9). If you're base64-encoding or truncating the output, use plain hex.

expired_timestamp

The t timestamp you supplied is more than 5 minutes old.

Fix: regenerate the timestamp each time you build a URL. This code applies to the legacy signed-URL flow; the current HMAC v2 flow has no timestamp.

invalid_api_key

The key you passed does not exist.

Fix: copy the full API key from the dashboard — it's the public identifier starting with sk_. It is public and safe in URLs; the secret (never in URLs) is what proves possession.

missing_hmac_secret

The API key has no HMAC secret configured.

Fix: create a new API key in the dashboard — the HMAC secret is generated and shown once at creation.

Parameter / input

invalid_image_url

A URL-bearing prop (image, brand_logo, logo, avatar, background_image, ...) is not a public http(s) URL.

Fix: pass a publicly fetchable https://... URL. Localhost, private IPs, and bare paths are rejected to prevent server-side request forgery.

Subscription

subscription_required (402)

The request hit the Dynamic API but your account has no active plan. API access is subscription-only: the plan is the gate, and it carries the same coverage + capability ladder the FastOG apps sell. Renders themselves are not metered — there is no monthly render quota and no overage billing.

Fix: choose a Dynamic API plan in the dashboard and create an API key. The response includes a top_up_url pointing at the plans page.

Render service

store_blocked (403)

Rendering for the store behind this key has been paused by FastOG (for example, abuse or runaway usage). Covers already cached at the edge may keep serving until they expire. Contact support to resolve it; nothing you can change in the request will fix this.

render_unreachable

The render service could not be reached (brief restart window).

Fix: retry in a few seconds. The render was not counted for this attempt.

render_failed

The render service returned an error for your request.

Fix: verify your template props — long/malformed values, unsupported fields, or an unreachable upstream image. The response includes the underlying status. The render was not counted.

Store admin surfaces

These codes answer from the Shopify admin and the WooCommerce Studio — the embedded editors a merchant works in rather than the signed API. Several are shared with the public API (invalid_image_url, render_failed, invalid_signature); those keep the entry documented above.

Wix bridge

The Wix bridge is signed by the Wix app, not a merchant session, so its failures are addressed to the app developer. Every response still carries code and request_id; the bridge request id is the one from the signed envelope.

Demo surface

The demo is the owner-only sales console, not a merchant endpoint.

Scoped-rule editor codes

The scoped-rule editors (Shopify admin and WooCommerce Studio) translate these tokens themselves, into the merchant's own language, so their responses carry error and code but no hint — a second English description would only drift from the localized one the merchant actually sees:

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.

Still stuck?

• Open the dashboard Render Logs page — every outcome (success + rejection) is listed with its error_code, HTTP status, and the requested params.
• Run php artisan og:diagnose on a signed URL to walk the whole pipeline and see which stage fails.
• Check the docs in the sidebar for the framework you're using (Next.js, Express, SvelteKit, ...).