API-hibák – Mit jelent az egyes kódok, és hogyan javíthatja őket

A FastOG géppel olvasható hibakódokat ad vissza, amikor egy kérés meghiúsul – legyen szó aláírt OG-kép rendereléséről vagy az egyik terméken belüli adminisztrációs felület hívásáról. Minden hibaüzenet tartalmazza a következőket:

• error — a régi rövid token. Minden hibánál továbbra is jelen van, hogy egy régebbi kliens továbbra is működjön.
• code — ugyanaz a stabil, dokumentált hibakód (lásd az alábbi táblázatot), a nyilvános API által használt néven.
• message — egy mondatos leírás arról, mi hibázott.
• hint — rövid, közérthető leírás arról, mi hibázott és hogyan javíthatja.
• docs_url — hivatkozás erre az oldalra, az adott kód szakaszához horgonyozva.
• request_id — összekapcsolja ezt a HTTP-hibát a dashboard Render Logs táblázatának egy sorával (a X-Request-ID válaszfejlécben is visszaadva). Az a felület, amelynél nincs mit összekapcsolni, null értéket ad vissza, de a kulcs mindig jelen van.

A terméken belüli felületek – a Shopify admin, a WooCommerce Studio, a Wix bridge és a demó – ugyanazzal a burkolóval (envelope) válaszolnak az alábbi kódokra, így egy hiba mindenhol ugyanazt jelenti, ahol találkozik vele. Egy modulfelület megtarthatja azt a HTTP-státuszt, amelyet egy kódhoz mindig is visszaadott (például a render_failed 503-mal válaszol a cover exportnál és 502-vel a nyilvános API-nál); a kód, az üzenet, a tipp és a dokumentációs hivatkozás nem változik.

Hibaválasz olvasása

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

Ha olyan választ kap, amelyet nem ért, a leggyorsabb út a következő:

1. Jegyezze fel a code értékét.
2. Ellenőrizze az URL-építőjét — a legtöbb hiba aláírási hiba, nem fiókprobléma.
3. Keresse meg az alábbiakban a pontos okot és a javítást a kód alapján.
4. A dashboardon nyissa meg a Render Logs oldalt, és szűrjön ugyanarra a error_code értékre — minden sor mutatja a kért paramétereket, így reprodukálhatja (és megerősítheti, hogy a request_id egyezik).

Aláírás és hitelesítés

missing_signature

A kéréséből hiányzik az key és/vagy a s (aláírás) query paraméter.

Javítás: győződjön meg róla, hogy az URL tartalmazza mind a key=<api-key>, mind a s=<hmac-signature> paramétert. Használja az SDK-t vagy az /docs/hmac-signature-guide útmutatót az URL összeállításához.

invalid_signature

A s értéke nem egyezett azzal, amit a HMAC titka ehhez az URL-hez előállít.

Javítás: az aláírás minden query paramétert lefed az s kivételével, a kulcsok szerint rendezve. Bármely paraméter módosítása — beleértve az átrendezést, az URL-kódolásbeli eltéréseket vagy szóközök hozzáadását — érvényteleníti az aláírást. Minden módosítás után írja alá újra. Győződjön meg róla, hogy ugyanazt a titkot használja, amelyet az API-kulcs létrehozásakor kapott.

invalid_signature_format

A s értéke nem egy 64 karakteres hexadecimális karakterlánc.

Javítás: az aláírásnak nyers SHA-256 hexnek kell lennie (kisbetűs a-f0-9). Ha base64-kódolást alkalmaz vagy csonkítja a kimenetet, használjon egyszerű hexet.

expired_timestamp

A megadott t időbélyeg több mint 5 perces.

Javítás: minden URL-építéskor generáljon új időbélyeget. Ez a kód a régi aláírt URL folyamatra vonatkozik; a jelenlegi HMAC v2 folyamatban nincs időbélyeg.

invalid_api_key

A megadott key nem létezik.

Javítás: másolja ki a teljes API-kulcsot a dashboardról — ez a sk_ előtaggal kezdődő nyilvános azonosító. Nyilvános, és biztonságos az URL-ekben; a titok (soha nem kerül URL-be) az, ami igazolja a birtoklást.

missing_hmac_secret

Az API-kulcshoz nincs beállítva HMAC titok.

Javítás: hozzon létre új API-kulcsot a dashboardon — a HMAC titok létrehozáskor generálódik, és csak egyszer jelenik meg.

Paraméter / bemenet

invalid_image_url

Egy URL-t tartalmazó prop (image, brand_logo, logo, avatar, background_image, ...) nem nyilvános http(s) URL.

Javítás: adjon át egy nyilvánosan elérhető https://... URL-t. A localhost, a privát IP-címek és a csupasz útvonalak elutasításra kerülnek a szerveroldali kéréshamisítás (server-side request forgery) megelőzése érdekében.

Előfizetés

subscription_required (402)

A kérés elérte a Dynamic API-t, de az Ön fiókjához nem tartozik aktív csomag. Az API-hozzáférés csak előfizetéssel érhető el: a csomag a belépési feltétel, és ugyanazt a lefedettségi és képességi szinteket kínálja, amelyeket a FastOG alkalmazásai értékesítenek. Maguk a renderelések nincsenek mérve — nincs havi renderkvóta és nincs túlhasználati számlázás.

Javítás: válasszon Dynamic API-csomagot a dashboardon, és hozzon létre egy API-kulcsot. A válasz tartalmaz egy top_up_url hivatkozást a csomagok oldalára.

Render szolgáltatás

store_blocked (403)

A kulcs mögötti áruház renderelését a FastOG szüneteltette (például visszaélés vagy túlzott használat miatt). Az edge-en már gyorsítótárazott borítók a lejáratukig továbbra is kiszolgálhatók. A megoldáshoz forduljon az ügyfélszolgálathoz; a kérésben semmit sem módosíthat, ami ezt orvosolná.

render_unreachable

A render szolgáltatás nem volt elérhető (rövid újraindítási ablak).

Javítás: próbálja újra néhány másodperc múlva. A renderelés nem került beszámításra ehhez a kísérlethez.

render_failed

A render szolgáltatás hibát adott vissza a kérésére.

Javítás: ellenőrizze a sablon props-értékeit — túl hosszú/rossz formátumú értékek, nem támogatott mezők vagy elérhetetlen upstream kép. A válasz tartalmazza a mögöttes status hibát. A renderelés nem került beszámításra.

Áruház-admin felületek

Ezek a kódok a Shopify adminból és a WooCommerce Studióból válaszolnak — a beágyazott szerkesztőkből, amelyekben a kereskedő dolgozik, nem pedig az aláírt API-ból. Több közülük közös a nyilvános API-val (invalid_image_url, render_failed, invalid_signature); ezek megtartják a fent dokumentált bejegyzést.

Wix híd

A Wix hidat a Wix alkalmazás írja alá, nem egy kereskedői munkamenet, ezért a hibái az alkalmazás fejlesztőjének szólnak. Minden válasz továbbra is tartalmazza a code és request_id fejlécet; a híd kérés-azonosítója a aláírt borítékból származó azonosító.

Demó felület

A demó a csak tulajdonos által elérhető értékesítési konzol, nem kereskedői végpont.

Hatókörszabály-szerkesztők kódjai

A hatókörszabály-szerkesztők (Shopify admin és WooCommerce Studio) maguk fordítják le ezeket a tokeneket a kereskedő saját nyelvére, ezért válaszaik error és code értéket tartalmaznak, de hint értéket nem — egy második angol leírás csak eltérne attól a lokalizált változattól, amelyet a kereskedő valójában lát:

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.

Még mindig elakadt?

• Nyissa meg a dashboard Render Logs oldalát — minden eredmény (siker + elutasítás) listázva van a error_code értékével, a HTTP státuszkóddal és a kért paraméterekkel.
• Futtassa a php artisan og:diagnose parancsot egy aláírt URL-en, hogy végigkövesse a teljes folyamatot, és lássa, melyik szakasz hibázik.
• Nézze meg az oldalsávban található dokumentációt az Ön által használt keretrendszerhez (Next.js, Express, SvelteKit, ...).