API-virheet — Mitä kukin koodi tarkoittaa ja miten se korjataan

FastOG palauttaa koneellisesti luettavia virhekoodeja, kun pyyntö epäonnistuu — allekirjoitettu OG-kuvan renderöinti tai kutsu johonkin tuotteen sisäiseen hallintapintaan. Jokainen virhevastaus sisältää:

• error — vanha lyhyt tunniste. Yhä mukana jokaisessa virheessä, jotta vanhempi asiakasohjelma toimii edelleen.
• code — sama vakaa, dokumentoitu virhekoodi (taulukko alla) sillä nimellä, jota julkinen API käyttää.
• message — yhden lauseen kuvaus siitä, mikä meni pieleen.
• hint — lyhyt selkokielinen kuvaus siitä, mikä meni pieleen ja miten se korjataan.
• docs_url — linkki tälle sivulle, ankkuroituna kyseisen koodin osioon.
• request_id — yhdistää tämän HTTP-virheen dashboardin Render Logs -taulukon riviin (palautetaan myös X-Request-ID-vastausotsakkeessa). Pinta, jolla ei ole mitään yhdistettävää, vastaa null, mutta avain on aina mukana.

Tuotteen sisäiset pinnat — Shopify-hallinta, WooCommerce Studio, Wix-silta ja demo — vastaavat samalla kirjekuorella alla oleville koodeille, joten virhe tarkoittaa samaa asiaa missä ikinä sen kohtaat. Moduulipinta voi säilyttää HTTP-tilakoodin, jonka se on aina palauttanut tietylle koodille (esimerkiksi render_failed vastaa 503 kansikuvan viennissä ja 502 julkisessa API:ssa); koodi, viesti, vihje ja dokumentaatiolinkki eivät muutu.

Virhevastauksen lukeminen

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

Jos saat vastauksen, jota et ymmärrä, nopein tapa on:

1. Kirjaa ylös code.
2. Tarkista URL-rakentajasi — useimmat virheet johtuvat allekirjoitusbugeista, eivät tiliin liittyvistä ongelmista.
3. Katso alla olevasta taulukosta tarkka syy ja korjaus.
4. Avaa hallintapaneelissa Render Logs ja suodata samalla error_code:lla — jokainen rivi näyttää pyydetyt parametrit, joten voit toistaa tilanteen (ja varmistaa, että request_id täsmää).

Allekirjoitus ja todennus

missing_signature

Pyynnöstäsi puuttuu key- ja/tai s-kyselyparametri (allekirjoitus).

Korjaus: varmista, että URL sisältää sekä key=<api-key> että s=<hmac-signature>. Käytä SDK:ta tai /docs/hmac-signature-guide-läpikäyntiä sen rakentamiseen.

invalid_signature

s-arvo ei vastannut sitä, mitä HMAC-salaisuutesi tuottaa tälle URL:lle.

Korjaus: allekirjoitus kattaa jokaisen kyselyparametrin paitsi s, avaimet lajiteltuina. Minkä tahansa parametrin muuttaminen — mukaan lukien uudelleenjärjestely, URL-koodauksen erot tai välilyönnin lisääminen — mitätöi allekirjoituksen. Allekirjoita uudelleen jokaisen muutoksen jälkeen. Varmista, että salaisuutesi on sama, joka näytettiin API-avainta luotaessa.

invalid_signature_format

s-arvo ei ole 64 merkin heksadesimaalimerkkijono.

Korjaus: allekirjoituksen on oltava raaka SHA-256 -heksadesimaali (pienet kirjaimet a-f0-9). Jos base64-koodaat tai katkaiset tulosteen, käytä pelkkää heksadesimaalia.

expired_timestamp

Antamasi t-aikaleima on yli 5 minuuttia vanha.

Korjaus: luo aikaleima uudelleen joka kerta, kun rakennat URL:n. Tämä koodi koskee vanhaa allekirjoitetun URL:n toimintatapaa; nykyisessä HMAC v2 -toimintatavassa ei ole aikaleimaa.

invalid_api_key

Antamaasi key ei ole olemassa.

Korjaus: kopioi täysi API-avain hallintapaneelista — se on julkinen tunniste, joka alkaa merkillä sk_. Se on julkinen ja turvallinen URL:issa; salaisuus (ei koskaan URL:issa) on se, joka todistaa hallussapidon.

missing_hmac_secret

API-avaimelle ei ole määritetty HMAC-salaisuutta.

Korjaus: luo uusi API-avain hallintapaneelissa — HMAC-salaisuus luodaan ja näytetään kerran luonnin yhteydessä.

Parametri / syöte

invalid_image_url

URL-osoitteen sisältävä prop (image, brand_logo, logo, avatar, background_image, ...) ei ole julkinen http(s)-URL.

Korjaus: välitä julkinen, haettavissa oleva https://...-URL. Localhost, yksityiset IP-osoitteet ja pelkät polut hylätään palvelinpuolen pyyntöjen väärentämisen (SSRF) estämiseksi.

Tilaus

subscription_required (402)

Pyyntö osui Dynamic API -rajapintaan, mutta tililläsi ei ole aktiivista suunnitelmaa. API-käyttö on vain tilauksella: suunnitelma on edellytys, ja se sisältää saman kattavuus- ja ominaisuusportaikon, jota FastOG-sovellukset myyvät. Itse renderöintejä ei laskuteta — kuukausittaista renderöintikiintiötä tai ylityslaskutusta ei ole.

Korjaus: valitse Dynamic API -suunnitelma hallintapaneelista ja luo API-avain. Vastaus sisältää top_up_url, joka osoittaa suunnitelmasivulle.

Renderöintipalvelu

store_blocked (403)

FastOG on keskeyttänyt tämän avaimen taustalla olevan kaupan renderöinnin (esimerkiksi väärinkäytön tai hallitsemattoman käytön vuoksi). Edgeen jo välimuistiin tallennetut kuvat voivat jatkaa tarjoilua, kunnes ne vanhenevat. Ota yhteyttä tukeen asian ratkaisemiseksi; mikään pyynnössä tehtävä muutos ei korjaa tätä.

render_unreachable

Renderöintipalveluun ei saatu yhteyttä (lyhyt uudelleenkäynnistysikkuna).

Korjaus: yritä uudelleen muutaman sekunnin kuluttua. Renderöintiä ei laskettu tästä yrityksestä.

render_failed

Renderöintipalvelu palautti virheen pyynnöllesi.

Korjaus: tarkista mallisi props-arvot — pitkät/virheelliset arvot, tukemattomat kentät tai tavoittamaton upstream-kuva. Vastaus sisältää taustalla olevan status. Renderöintiä ei laskettu.

Verkkokaupan ylläpitoliittymät

Nämä koodit vastaavat Shopify-administa ja WooCommerce Studiosta — upotetuista editoreista, joissa kauppias työskentelee allekirjoitetun API:n sijaan. Useat ovat yhteisiä julkisen API:n kanssa (invalid_image_url, render_failed, invalid_signature); ne säilyttävät yllä dokumentoidun merkinnän.

Wix-silta

Wix-sillan allekirjoittaa Wix-sovellus, ei kauppiaan istunto, joten sen virheet on osoitettu sovelluskehittäjälle. Jokainen vastaus sisältää silti code ja request_id; sillan pyyntötunnus on se, joka on allekirjoitetussa kirjekuoressa.

Demoympäristö

Demo on vain omistajalle tarkoitettu myyntikonsoli, ei kauppiaan päätepiste.

Scoped-rule-editorien koodit

Scoped-rule-editorit (Shopify admin ja WooCommerce Studio) kääntävät nämä tokenit itse kauppiaan omalle kielelle, joten niiden vastaukset sisältävät error ja code mutta eivät hint — toinen englanninkielinen kuvaus poikkeaisi vain lokalisoidusta versiosta, jonka kauppias todella näkee:

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.

Vieläkö jumissa?

• Avaa dashboardin Render Logs -sivu — jokainen tulos (onnistuminen + hylkäys) listataan sen error_code, HTTP-tilan ja pyydettyjen parametrien kanssa.
• Aja php artisan og:diagnose allekirjoitetulle URL:lle käydäksesi läpi koko putken ja nähdäksesi, mikä vaihe epäonnistuu.
• Tarkista sivupalkin dokumentaatiosta käyttämäsi kehys (Next.js, Express, SvelteKit, ...).