API-feil — hva hver kode betyr og hvordan du retter den

FastOG returnerer maskinlesbare feilkoder når en forespørsel feiler — en signert OG-bilde-render, eller et kall til en av de innebygde admin-flatene. Hvert feilsvar inneholder:

• error — den eldre korte tokenen. Finnes fortsatt på hver feil, slik at en eldre klient fortsatt fungerer.
• code — den samme stabile, dokumenterte feilkoden (tabellen nedenfor), under navnet det offentlige API-et bruker.
• message — en setning som beskriver hva som gikk galt.
• hint — en kort beskrivelse på klarspråk av hva som gikk galt og hvordan du retter det.
• docs_url — en lenke til denne siden, ankret til seksjonen for den koden.
• request_id — korrelerer denne HTTP-feilen med en rad i Render Logs-tabellen i dashbordet (returneres også i X-Request-ID-svarshodet). En flate uten noe å korrelere svarer null, men nøkkelen finnes alltid.

De innebygde flatene — Shopify-adminen, WooCommerce Studio, Wix-broen og demoen — svarer med samme konvolutt for kodene nedenfor, så en feil betyr det samme uansett hvor du møter den. En modulflate kan beholde HTTP-statusen den alltid har returnert for en kode (for eksempel svarer render_failed 503 på cover-eksporten og 502 på det offentlige API-et); koden, meldingen, hintet og dokumentasjonslenken endres ikke.

Lesing av en feilrespons

{
  "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 raskeste veien:

1. Noter code.
2. Sjekk URL-byggeren din — de fleste feil skyldes signeringsfeil, ikke kontoproblemer.
3. Slå opp koden nedenfor for å finne den nøyaktige årsaken og løsningen.
4. I dashbordet åpner du Render Logs og filtrerer på samme error_code — hver rad viser de forespurte parameterne, slik at du kan reprodusere (og bekrefte at request_id stemmer).

Signering og autentisering

missing_signature

Forespørselen din mangler spørringsparameterne key og/eller s (signatur).

Løsning: sørg for at URL-en inneholder både key=<api-key> og s=<hmac-signature>. Bruk SDK-et eller gjennomgangen av /docs/hmac-signature-guide for å bygge den.

invalid_signature

Verdien for s samsvarte ikke med det HMAC-hemmeligheten din produserer for denne URL-en.

Løsning: signaturen dekker alle spørringsparametere unntatt s, med sorterte nøkler. Endring av en hvilken som helst parameter – inkludert omorganisering, forskjeller i URL-koding eller ekstra mellomrom – ugyldiggjør signaturen. Signer på nytt etter hver endring. Bekreft at hemmeligheten din er den samme som ble vist da API-nøkkelen ble opprettet.

invalid_signature_format

Verdien for s er ikke en hex-streng på 64 tegn.

Løsning: signaturen må være rå SHA-256-hex (små bokstaver a-f0-9). Hvis du base64-koder eller trunkerer utdataene, bruk vanlig hex i stedet.

expired_timestamp

Tidsstempelet t du oppgav, er mer enn 5 minutter gammelt.

Løsning: generer tidsstempelet på nytt hver gang du bygger en URL. Denne koden gjelder den eldre flyten med signerte URL-er; den gjeldende HMAC v2-flyten har ikke noe tidsstempel.

invalid_api_key

key du sendte inn, finnes ikke.

Løsning: kopier hele API-nøkkelen fra dashbordet – det er den offentlige identifikatoren som starter med sk_. Den er offentlig og trygg å ha i URL-er; det er hemmeligheten (aldri i URL-er) som beviser at du har den.

missing_hmac_secret

API-nøkkelen har ingen HMAC-hemmelighet konfigurert.

Løsning: opprett en ny API-nøkkel i dashbordet – HMAC-hemmeligheten genereres og vises én gang ved opprettelsen.

Parameter / input

invalid_image_url

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

Løsning: send inn en offentlig tilgjengelig https://...-URL. Localhost, private IP-er og bare stier avvises for å forhindre server-side request forgery.

Abonnement

subscription_required (402)

Forespørselen traff Dynamic API, men kontoen din har ingen aktiv plan. API-tilgang er kun for abonnenter: planen er porten, og den har samme deknings- og funksjonsstige som FastOG-appene selger. Selve renderingen måles ikke — det finnes ingen månedlig render-kvote og ingen fakturering for overforbruk.

Løsning: velg en Dynamic API-plan i dashbordet og opprett en API-nøkkel. Svaret inneholder en top_up_url som peker til plansiden.

Gjengivelsestjeneste

store_blocked (403)

Gjengivelse for butikken bak denne nøkkelen er satt på pause av FastOG (for eksempel misbruk eller ukontrollert bruk). Bilder som allerede er bufret ved edge, kan fortsette å bli servert til de utløper. Kontakt support for å løse det; ingenting du kan endre i forespørselen vil fikse dette.

render_unreachable

Gjengivelsestjenesten kunne ikke nås (kort omstartsvindu).

Løsning: prøv igjen om noen sekunder. Gjengivelsen ble ikke talt for dette forsøket.

render_failed

Gjengivelsestjenesten returnerte en feil for forespørselen din.

Løsning: verifiser malens props — lange/feilformede verdier, felter som ikke støttes, eller et upstream-bilde som ikke kan nås. Svaret inneholder den underliggende status. Gjengivelsen ble ikke talt.

Administrasjonsflater i butikken

Disse kodene svarer fra Shopify-administrasjonen og WooCommerce Studio — de innebygde editorne en kjøpmann jobber i, snarere enn det signerte API-et. Flere er delt med det offentlige API-et (invalid_image_url, render_failed, invalid_signature); de beholder oppføringen som er dokumentert ovenfor.

Wix-bro

Wix-broen signeres av Wix-appen, ikke av en kjøpmannsøkt, så feilene rettes til apputvikleren. Hvert svar inneholder fortsatt code og request_id; bro-forespørselens id er den fra den signerte konvolutten.

Demoflate

Demoen er den eierbare salgskonsollen, ikke et forhandlerendepunkt.

Koder for regelredigering med begrenset omfang

Redigeringsverktøyene for regler med begrenset omfang (Shopify-administrasjonen og WooCommerce Studio) oversetter disse tokenene selv, til kjøpmannens eget språk, slik at svarene deres inneholder error og code, men ingen hint — en ekstra engelsk beskrivelse ville bare avvike fra den lokaliserte versjonen kjøpmannen 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.

Fortsatt fast?

• Åpne Render Logs-siden i dashbordet — hvert utfall (suksess + avvisning) listes opp med sin error_code, HTTP-status og de forespurte parameterne.
• Kjør php artisan og:diagnose på en signert URL for å gå gjennom hele pipelinen og se hvilket trinn som feiler.
• Sjekk dokumentasjonen i sidepanelet for rammeverket du bruker (Next.js, Express, SvelteKit, ...).