API-fejl — hvad hver kode betyder, og hvordan du retter den

FastOG returnerer maskinlæsbare fejlkoder, når en anmodning fejler — en signeret OG-billedrendering eller et kald til en af de indbyggede admin-flader. Hvert fejlsvar indeholder:

• error — det ældre korte token. Stadig til stede ved hver fejl, så en ældre klient fortsat virker.
• code — den samme stabile, dokumenterede fejlkode (tabellen nedenfor) under det navn, den offentlige API bruger.
• message — en beskrivelse på én sætning af, hvad der gik galt.
• hint — en kort beskrivelse i almindeligt sprog af, hvad der gik galt, og hvordan du retter det.
• docs_url — et link til denne side, forankret ved afsnittet for den pågældende kode.
• request_id — korrelerer denne HTTP-fejl med en række i dashboardets Render Logs-tabel (returneres også i X-Request-ID-svarshovedet). En flade uden noget at korrelere svarer null, men nøglen er altid til stede.

De indbyggede flader — Shopify-adminen, WooCommerce Studio, Wix-broen og demoen — svarer med den samme envelope for koderne nedenfor, så en fejl betyder det samme, uanset hvor du møder den. En modulflade kan beholde den HTTP-status, den altid har returneret for en kode (for eksempel svarer render_failed 503 på cover-eksporten og 502 på den offentlige API); koden, meddelelsen, hintet og docs-linket ændres ikke.

Læsning af et fejlsvar

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

Hvis du får et svar, du ikke forstår, er den hurtigste vej:

1. Notér code.
2. Tjek din URL-builder — de fleste fejl skyldes signeringsfejl, ikke problemer med kontoen.
3. Find den præcise årsag og løsning i koden nedenfor.
4. Åbn Render Logs i dashboardet, og filtrér efter samme error_code — hver række viser de anmodede parametre, så du kan reproducere (og bekræfte, at request_id stemmer).

Signering & godkendelse

missing_signature

Din anmodning mangler query-parametrene key og/eller s (signatur).

Ret: sørg for, at din URL indeholder både key=<api-key> og s=<hmac-signature>. Brug SDK'et eller gennemgangen af /docs/hmac-signature-guide til at bygge den.

invalid_signature

Værdien s matchede ikke det, som din HMAC-hemmelighed producerer for denne URL.

Ret: signaturen dækker alle query-parametre undtagen s, med sorterede nøgler. Ændring af en hvilken som helst parameter — herunder omarrangering, forskelle i URL-encoding eller tilføjelse af whitespace — ugyldiggør signaturen. Signer igen efter hver ændring. Bekræft, at din hemmelighed er den samme, som blev vist, da API-nøglen blev oprettet.

invalid_signature_format

Værdien s er ikke en hex-streng på 64 tegn.

Ret: signaturen skal være rå SHA-256-hex (små bogstaver a-f0-9). Hvis du base64-encoder eller afkorter outputtet, skal du bruge almindelig hex i stedet.

expired_timestamp

Det tidsstempel t, du angav, er mere end 5 minutter gammelt.

Ret: generér tidsstemplet på ny, hver gang du bygger en URL. Denne kode gælder for det legacy signerede-URL-flow; det nuværende HMAC v2-flow har intet tidsstempel.

invalid_api_key

Den key, du sendte, findes ikke.

Ret: kopiér den fulde API-nøgle fra dashboardet — det er den offentlige identifikator, der starter med sk_. Den er offentlig og sikker i URL'er; det er hemmeligheden (aldrig i URL'er), der beviser ejerskab.

missing_hmac_secret

API-nøglen har ingen HMAC-hemmelighed konfigureret.

Ret: opret en ny API-nøgle i dashboardet — HMAC-hemmeligheden genereres og vises én gang ved oprettelsen.

Parameter / input

invalid_image_url

En prop, der indeholder en URL (image, brand_logo, logo, avatar, background_image, ...), er ikke en offentlig http(s)-URL.

Rettelse: send en offentligt tilgængelig https://...-URL. Localhost, private IP-adresser og bare stier afvises for at forhindre server-side request forgery.

Abonnement

subscription_required (402)

Anmodningen ramte Dynamic API, men din konto har ikke en aktiv plan. API-adgang er kun for abonnenter: planen er adgangsbetingelsen, og den bærer samme dækning + kapabilitetstrappe, som FastOG-appsene sælger. Selve renderingerne måles ikke — der er ingen månedlig render-kvote og ingen fakturering for overforbrug.

Løsning: vælg en Dynamic API-plan i dashboardet, og opret en API-nøgle. Svaret indeholder en top_up_url, der peger på plansiden.

Render-tjeneste

store_blocked (403)

Rendering for butikken bag denne nøgle er blevet sat på pause af FastOG (for eksempel misbrug eller ukontrolleret forbrug). Caches, der allerede er gemt ved edge, kan fortsætte med at blive serveret, indtil de udløber. Kontakt support for at løse det; intet, du kan ændre i forespørgslen, vil rette dette.

render_unreachable

Render-tjenesten kunne ikke nås (kort genstartsvindue).

Løsning: prøv igen om et par sekunder. Renderingen blev ikke talt med for dette forsøg.

render_failed

Render-tjenesten returnerede en fejl for din forespørgsel.

Løsning: verificer dine template-props — lange/fejlbehæftede værdier, ikke-understøttede felter eller et utilgængeligt upstream-billede. Svaret indeholder den underliggende status. Renderingen blev ikke talt med.

Butikadmin-flader

Disse koder svarer fra Shopify-admin og WooCommerce Studio — de indlejrede editorer, som en merchant arbejder i frem for det signerede API. Flere deles med det offentlige API (invalid_image_url, render_failed, invalid_signature); de beholder den post, der er dokumenteret ovenfor.

Wix-bro

Wix-broen signeres af Wix-appen, ikke af en merchantsession, så dens fejl er rettet til app-udvikleren. Hvert svar bærer stadig code og request_id; broens request-id er det fra den signerede envelope.

Demooverflade

Demoen er den ejer-only salgskonsol, ikke et merchant-endpoint.

Scoped-rule editor-koder

Scoped-rule-editorerne (Shopify admin og WooCommerce Studio) oversætter selv disse tokens til forhandlerens eget sprog, så deres svar indeholder error og code, men ingen hint — en ekstra engelsk beskrivelse ville blot afvige fra den lokaliserede, som forhandleren faktisk ser:

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.

Stadig problemer?

• Åbn Render Logs-siden i dashboardet — hvert resultat (succes + afvisning) er listet med sin error_code, HTTP-status og de anmodede parametre.
• Kør php artisan og:diagnose på en signeret URL for at gennemgå hele pipelinen og se, hvilket trin der fejler.
• Tjek dokumentationen i sidepanelet for det framework, du bruger (Next.js, Express, SvelteKit, ...).