API-fel — vad varje kod betyder och hur du åtgärdar den

FastOG returnerar maskinläsbara felkoder när en begäran misslyckas — en signerad OG-Bild-rendering, eller ett anrop till en av produktens adminytor. Varje felsvar innehåller:

• error — den äldre korta token. Finns fortfarande kvar vid varje fel så att en äldre klient fortsätter att fungera.
• code — samma stabila, dokumenterade felkod (tabellen nedan), under det namn som det publika API:et använder.
• message — en mening som beskriver vad som gick fel.
• hint — en kort beskrivning på klarspråk av vad som gick fel och hur du åtgärdar det.
• docs_url — en länk till den här sidan, ankrad vid avsnittet för den koden.
• request_id — kopplar detta HTTP-fel till en rad i dashboardens Render Logs-tabell (returneras även i svarshuvudet X-Request-ID). En yta utan något att koppla till svarar null, men nyckeln finns alltid med.

Produktens ytor — Shopify-adminen, WooCommerce Studio, Wix-bryggan och demon — svarar med samma envelope för koderna nedan, så ett fel betyder samma sak var du än stöter på det. En modyta kan behålla den HTTP-status som den alltid har returnerat för en kod (till exempel svarar render_failed 503 på cover-exporten och 502 på det publika API:et); koden, meddelandet, tipset och dokumentationslänken ändras inte.

Läsa ett felsvar

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

Om du får ett svar som du inte förstår är den snabbaste vägen:

1. Notera code.
2. Kontrollera din URL-byggare — de flesta fel beror på signeringsbuggar, inte på kontoproblem.
3. Matcha koden nedan för att hitta den exakta orsaken och åtgärden.
4. Öppna Render Logs i instrumentpanelen och filtrera på samma error_code — varje rad visar de begärda parametrarna så att du kan reproducera (och bekräfta att request_id matchar).

Signering & autentisering

missing_signature

Din förfrågan saknar query-parametrarna key och/eller s (signatur).

Åtgärd: se till att din URL innehåller både key=<api-key> och s=<hmac-signature>. Använd SDK:t eller genomgången av /docs/hmac-signature-guide för att bygga den.

invalid_signature

Värdet på s matchade inte det som din HMAC-hemlighet producerar för den här URL:en.

Åtgärd: signaturen omfattar alla query-parametrar utom s, med nycklarna sorterade. Om du ändrar någon parameter — inklusive att ändra ordning, skillnader i URL-kodning eller att lägga till blanksteg — blir signaturen ogiltig. Signera om efter varje ändring. Bekräfta att din hemlighet är samma som den som visades när API-nyckeln skapades.

invalid_signature_format

Värdet på s är inte en hex-sträng på 64 tecken.

Åtgärd: signaturen måste vara rå SHA-256-hex (gemener a-f0-9). Om du base64-kodar eller trunkerar utdata, använd vanlig hex i stället.

expired_timestamp

Tidsstämpeln t som du angav är mer än 5 minuter gammal.

Åtgärd: generera om tidsstämpeln varje gång du bygger en URL. Den här koden gäller det äldre flödet med signerade URL:er; det nuvarande HMAC v2-flödet har ingen tidsstämpel.

invalid_api_key

key som du angav finns inte.

Åtgärd: kopiera hela API-nyckeln från instrumentpanelen — det är den publika identifieraren som börjar med sk_. Den är publik och säker att ha i URL:er; det är hemligheten (aldrig i URL:er) som bevisar innehav.

missing_hmac_secret

API-nyckeln har ingen HMAC-hemlighet konfigurerad.

Åtgärd: skapa en ny API-nyckel i instrumentpanelen — HMAC-hemligheten genereras och visas en gång vid skapandet.

Parameter / indata

invalid_image_url

En prop som innehåller en URL (image, brand_logo, logo, avatar, background_image, ...) är inte en offentlig http(s)-URL.

Åtgärd: skicka en offentligt hämtbar https://...-URL. Localhost, privata IP-adresser och enbart sökvägar avvisas för att förhindra server-side request forgery.

Abonnemang

subscription_required (402)

Begäran nådde Dynamic API men ditt konto har ingen aktiv plan. API-åtkomst är endast för abonnemang: planen är grinden, och den bär samma täcknings- och kapacitetsstege som FastOG-apparna säljer. Själva renderingarna mäts inte — det finns ingen månatlig renderingskvot och ingen överbruksfakturering.

Åtgärd: välj en Dynamic API-plan i instrumentpanelen och skapa en API-nyckel. Svaret innehåller en top_up_url som pekar på plansidan.

Renderingstjänst

store_blocked (403)

Renderingen för butiken bakom den här nyckeln har pausats av FastOG (till exempel missbruk eller skenande användning). Cachar som redan finns i edge-nätverket kan fortsätta att serveras tills de löper ut. Kontakta supporten för att lösa det; inget du kan ändra i begäran kommer att åtgärda detta.

render_unreachable

Renderingstjänsten kunde inte nås (ett kort omstartsfönster).

Åtgärd: försök igen om några sekunder. Renderingen räknades inte för det här försöket.

render_failed

Renderingstjänsten returnerade ett fel för din begäran.

Åtgärd: kontrollera dina template-props — långa/ felaktiga värden, fält som inte stöds eller en bild från en uppströmskälla som inte går att nå. Svaret innehåller det underliggande status. Renderingen räknades inte.

Butiksadminytor

Dessa koder svarar från Shopify-adminen och WooCommerce Studio — de inbäddade redigerarna som en handlare arbetar i snarare än det signerade API:et. Flera delas med det publika API:et (invalid_image_url, render_failed, invalid_signature); de behåller posten som dokumenteras ovan.

Wix-brygga

Wix-bryggan signeras av Wix-appen, inte av en handlarsession, så dess fel riktas till apputvecklaren. Varje svar innehåller fortfarande code och request_id; bryggans request-id är det från det signerade kuvertet.

Demoyta

Demon är den ägarexklusiva säljkonsolen, inte en handlarendpoint.

Koder för scoped-rule-redigerare

Redigerarna för scoped rules (Shopify admin och WooCommerce Studio) översätter dessa tokens själva till handlarens eget språk, så deras svar innehåller error och code men ingen hint — en andra engelsk beskrivning skulle bara glida ifrån den lokaliserade version som handlaren faktiskt 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.

Fortfarande fast?

• Öppna sidan Render Logs i instrumentpanelen (dashboard) — varje utfall (lyckat + avvisat) listas med sin error_code, HTTP-status och de begärda parametrarna.
• Kör php artisan og:diagnose på en signerad URL för att gå igenom hela flödet och se vilket steg som misslyckas.
• Kolla dokumentationen i sidopanelen för det ramverk du använder (Next.js, Express, SvelteKit, ...).