Chyby API — co který kód znamená a jak ho opravit

FastOG vrací strojově čitelné chybové kódy, když požadavek selže — ať už jde o vykreslení podepsaného OG obrázku, nebo volání jedné z administračních ploch přímo v produktu. Každá chybová odpověď obsahuje:

• error — původní krátký token. Zůstává u každého selhání, aby starší klient fungoval dál.
• code — stejný stabilní, zdokumentovaný chybový kód (tabulka níže), pod názvem, který používá veřejné API.
• message — jednořádkový popis toho, co se pokazilo.
• hint — krátký popis jednoduchým jazykem, co se pokazilo a jak to opravit.
• docs_url — odkaz na tuto stránku ukotvený na sekci daného kódu.
• request_id — propojuje toto HTTP selhání s řádkem v tabulce Render Logs v dashboardu (vrací se také v hlavičce odpovědi X-Request-ID). Plocha, která nemá co propojit, odpovídá null, ale klíč je vždy přítomný.

Plochy přímo v produktu — Shopify admin, WooCommerce Studio, Wix bridge a demo — odpovídají stejnou obálkou pro níže uvedené kódy, takže selhání znamená totéž, ať na něj narazíš kdekoli. Plocha modulu si může ponechat HTTP status, který vracela vždy pro daný kód (například render_failed odpovídá 503 u exportu obálky a 502 u veřejného API); kód, zpráva, nápověda ani odkaz na dokumentaci se nemění.

Čtení chybové odpovědi

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

Pokud dostaneš odpověď, které nerozumíš, nejrychlejší postup je:

1. Poznamenej si code.
2. Zkontroluj svůj URL builder — většina selhání jsou chyby v podpisu, ne problémy s účtem.
3. Podle kódu níže najdi přesnou příčinu a opravu.
4. V dashboardu otevři Render Logs a filtruj podle stejného error_code — každý řádek zobrazuje požadované parametry, takže můžeš reprodukovat (a ověřit, že request_id sedí).

Podepisování a autentizace

missing_signature

V tvém požadavku chybí query parametry key a/nebo s (podpis).

Oprava: ujisti se, že tvá URL obsahuje jak key=<api-key>, tak s=<hmac-signature>. Použij SDK nebo postup /docs/hmac-signature-guide pro její sestavení.

invalid_signature

Hodnota s neodpovídala tomu, co pro tuto URL vytváří tvůj HMAC secret.

Oprava: podpis pokrývá všechny query parametry kromě s, s klíči seřazenými. Změna jakéhokoli parametru — včetně přeřazení, rozdílů v URL-encoding nebo přidání bílého znaku — podpis zneplatní. Po každé změně podepiš znovu. Ověř, že tvůj secret je stejný jako ten, který se zobrazil při vytvoření API klíče.

invalid_signature_format

Hodnota s není 64znakový hex řetězec.

Oprava: podpis musí být raw SHA-256 hex (malá písmena a-f0-9). Pokud výstup kóduješ do base64 nebo ho zkracuješ, použij prostý hex.

expired_timestamp

Časové razítko t, které jsi poskytl, je starší než 5 minut.

Oprava: generuj časové razítko znovu pokaždé, když sestavuješ URL. Tento kód se týká staršího postupu s podepsanou URL; aktuální postup HMAC v2 žádné časové razítko nemá.

invalid_api_key

key, které jsi předal, neexistuje.

Oprava: zkopíruj celý API klíč z dashboardu — je to veřejný identifikátor začínající na sk_. Je veřejný a v URL je bezpečný; secret (nikdy v URL) je to, co prokazuje vlastnictví.

missing_hmac_secret

API klíč nemá nakonfigurovaný HMAC secret.

Oprava: vytvoř v dashboardu nový API klíč — HMAC secret se vygeneruje a zobrazí jednou při vytvoření.

Parametr / vstup

invalid_image_url

Prop nesoucí URL (image, brand_logo, logo, avatar, background_image, ...) není veřejná http(s) URL.

Oprava: předej veřejně dostupnou URL https://.... Localhost, privátní IP adresy a samotné cesty jsou odmítnuty, aby se zabránilo server-side request forgery.

Předplatné

subscription_required (402)

Požadavek dorazil na Dynamic API, ale tvůj účet nemá aktivní plán. Přístup k API je pouze na předplatné: plán je podmínkou a nese stejnou škálu pokrytí a možností, jakou prodávají aplikace FastOG. Samotné rendery se neměří — neexistuje měsíční kvóta renderů ani účtování nadlimitního čerpání.

Oprava: vyber v dashboardu plán Dynamic API a vytvoř API klíč. Odpověď obsahuje top_up_url odkazující na stránku s plány.

Služba vykreslování

store_blocked (403)

Vykreslování pro obchod za tímto klíčem bylo FastOG pozastaveno (například kvůli zneužití nebo nekontrolovanému využívání). Obaly již uložené v mezipaměti na edge mohou dál sloužit, dokud nevyprší. Pro vyřešení kontaktuj podporu; nic, co můžeš změnit v požadavku, to neopraví.

render_unreachable

Službu vykreslování nebylo možné kontaktovat (krátké okno restartu).

Oprava: zkus to znovu za několik sekund. Vykreslení se pro tento pokus nezapočítalo.

render_failed

Služba vykreslování vrátila pro tvůj požadavek chybu.

Oprava: zkontroluj props své šablony — dlouhé/chybně formátované hodnoty, nepodporovaná pole nebo nedostupný upstream obrázek. Odpověď obsahuje podkladovou status. Vykreslení se nezapočítalo.

Administrátorská rozhraní obchodu

Tyto kódy odpovídají z administrace Shopify a z WooCommerce Studio — z vestavěných editorů, ve kterých obchodník pracuje, nikoli z podepsaného API. Několik z nich je společných s veřejným API (invalid_image_url, render_failed, invalid_signature); ty si zachovávají výše zdokumentovanou položku.

Wix bridge

Wix bridge je podepisován aplikací Wix, nikoli relací obchodníka, takže jeho chyby jsou adresovány vývojáři aplikace. Každá odpověď stále nese code a request_id; id požadavku bridge je to z podepsaného obalu.

Demo plocha

Demo je prodejní konzole pouze pro vlastníka, nikoli endpoint pro obchodníky.

Kódy editorů pravidel s rozsahem

Editory pravidel s rozsahem (Shopify admin a WooCommerce Studio) si tyto tokeny překládají samy do jazyka obchodníka, takže jejich odpovědi obsahují error a code, ale žádné hint — druhý anglický popis by se jen rozešel s lokalizovaným popisem, který obchodník skutečně vidí:

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.

Stále máš problém?

• Otevři stránku Render Logs v dashboardu — každý výsledek (úspěch i odmítnutí) je uveden s error_code, stavovým kódem HTTP a požadovanými parametry.
• Spusť php artisan og:diagnose na podepsané URL, abys prošel celý pipeline a zjistil, která fáze selhává.
• Podívej se do dokumentace v postranním panelu pro framework, který používáš (Next.js, Express, SvelteKit, ...).