API-fouten — Wat elke code betekent en hoe je het oplost

FastOG retourneert machineleesbare foutcodes wanneer een verzoek mislukt — een ondertekende OG-afbeelding renderen, of een aanroep naar een van de admin-oppervlakken in het product. Elke foutrespons bevat:

• error — het legacy korte token. Nog steeds aanwezig bij elke fout, zodat een oudere client blijft werken.
• code — dezelfde stabiele, gedocumenteerde foutcode (tabel hieronder), onder de naam die de publieke API gebruikt.
• message — een beschrijving van één zin van wat er misging.
• hint — een korte beschrijving in gewone taal van wat er misging en hoe je het oplost.
• docs_url — een link naar deze pagina, verankerd op de sectie voor die code.
• request_id — koppelt deze HTTP-fout aan een rij in de Render Logs-tabel van het dashboard (ook teruggegeven in de X-Request-ID-responsheader). Een oppervlak zonder iets om aan te koppelen antwoordt met null, maar de sleutel is altijd aanwezig.

De oppervlakken in het product — de Shopify-admin, de WooCommerce Studio, de Wix-bridge en de demo — antwoorden met dezelfde envelope voor de onderstaande codes, dus een fout betekent hetzelfde waar je die ook tegenkomt. Een module-oppervlak kan de HTTP-status behouden die het altijd al teruggaf voor een code (bijvoorbeeld render_failed antwoordt 503 bij de cover-export en 502 bij de publieke API); de code, het bericht, de hint en de docs-link veranderen niet.

Een foutrespons lezen

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

Als je een respons krijgt die je niet begrijpt, is dit de snelste route:

1. Noteer de code.
2. Controleer je URL-builder — de meeste fouten zijn bugs in de signing, geen accountproblemen.
3. Zoek de code hieronder op voor de exacte oorzaak en oplossing.
4. Open in het dashboard Render Logs en filter op dezelfde error_code — elke rij toont de opgevraagde params, zodat je het kunt reproduceren (en kunt bevestigen dat request_id overeenkomt).

Ondertekenen & authenticatie

missing_signature

Je verzoek mist de queryparameters key en/of s (signature).

Oplossing: zorg dat je URL zowel key=<api-key> als s=<hmac-signature> bevat. Gebruik de SDK of de /docs/hmac-signature-guide-walkthrough om hem op te bouwen.

invalid_signature

De waarde van s kwam niet overeen met wat je HMAC-secret voor deze URL oplevert.

Oplossing: de signature dekt elke queryparameter behalve s, met gesorteerde keys. Het wijzigen van welke parameter dan ook — inclusief herordenen, verschillen in URL-encoding of toegevoegde whitespace — maakt de signature ongeldig. Onderteken opnieuw na elke wijziging. Controleer of je secret hetzelfde is als het secret dat werd getoond bij het aanmaken van de API key.

invalid_signature_format

De waarde van s is geen hex-string van 64 tekens.

Oplossing: de signature moet raw SHA-256 hex zijn (kleine letters a-f0-9). Als je de output base64-encodeert of afkapt, gebruik dan gewone hex.

expired_timestamp

De t-timestamp die je hebt opgegeven is ouder dan 5 minuten.

Oplossing: genereer de timestamp opnieuw telkens wanneer je een URL opbouwt. Deze code geldt voor de legacy signed-URL-flow; de huidige HMAC v2-flow heeft geen timestamp.

invalid_api_key

De key die je hebt doorgegeven bestaat niet.

Oplossing: kopieer de volledige API key uit het dashboard — het is de publieke identifier die begint met sk_. Hij is publiek en veilig in URL's; het secret (nooit in URL's) is wat het bezit bewijst.

missing_hmac_secret

Voor de API key is geen HMAC-secret geconfigureerd.

Oplossing: maak een nieuwe API key aan in het dashboard — het HMAC-secret wordt gegenereerd en eenmalig getoond bij het aanmaken.

Parameter / invoer

invalid_image_url

Een prop met een URL (image, brand_logo, logo, avatar, background_image, ...) is geen openbare http(s)-URL.

Oplossing: geef een openbaar op te halen https://... URL door. Localhost, privé-IP's en kale paden worden geweigerd om server-side request forgery te voorkomen.

Abonnement

subscription_required (402)

Het verzoek bereikte de Dynamic API, maar je account heeft geen actief plan. API-toegang is alleen met een abonnement: het plan is de toegangspoort en biedt dezelfde dekking en mogelijkhedenschaal die de FastOG-apps verkopen. Renders zelf worden niet gemeten — er is geen maandelijkse renderc quota en geen facturering voor overschrijding.

Oplossing: kies een Dynamic API-plan in het dashboard en maak een API-sleutel aan. Het antwoord bevat een top_up_url die naar de plannenpagina verwijst.

Render-service

store_blocked (403)

Het renderen voor de store achter deze key is door FastOG gepauzeerd (bijvoorbeeld door misbruik of buitensporig gebruik). Covers die al in de edge-cache staan, kunnen blijven serveren tot ze verlopen. Neem contact op met support om dit op te lossen; niets wat je in het request kunt wijzigen lost dit op.

render_unreachable

De render-service was niet bereikbaar (kort herstartvenster).

Oplossing: probeer het over een paar seconden opnieuw. De render is niet geteld voor deze poging.

render_failed

De render-service gaf een fout terug voor je request.

Oplossing: controleer je template-props — lange of misvormde waarden, niet-ondersteunde velden, of een niet-bereikbare upstream-afbeelding. De response bevat de onderliggende status. De render is niet geteld.

Beheeromgevingen van de winkel

Deze codes antwoorden vanuit de Shopify-admin en de WooCommerce Studio — de ingebedde editors waarin een merchant werkt in plaats van de ondertekende API. Verschillende worden gedeeld met de publieke API (invalid_image_url, render_failed, invalid_signature); die behouden de hierboven gedocumenteerde vermelding.

Wix-bridge

De Wix-bridge wordt ondertekend door de Wix-app, niet door een merchantsessie, dus de fouten ervan zijn gericht aan de app-ontwikkelaar. Elke response bevat nog steeds code en request_id; het bridge-request-id is dat uit de ondertekende envelope.

Demo-omgeving

De demo is de verkoopconsole die alleen voor de eigenaar toegankelijk is, geen merchant-endpoint.

Codes voor de scoped-rule-editor

De scoped-rule-editors (Shopify admin en WooCommerce Studio) vertalen deze tokens zelf, naar de taal van de merchant, dus hun responses bevatten error en code maar geen hint — een tweede Engelse beschrijving zou alleen afwijken van de gelokaliseerde versie die de merchant daadwerkelijk ziet:

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.

Loop je nog ergens tegenaan?

• Open de pagina Render Logs in het dashboard — elke uitkomst (geslaagd + afgewezen) staat er met de bijbehorende error_code, HTTP-status en de opgevraagde params.
• Voer php artisan og:diagnose uit op een ondertekende URL om de hele pipeline te doorlopen en te zien welke stap faalt.
• Bekijk de documentatie in de zijbalk voor het framework dat je gebruikt (Next.js, Express, SvelteKit, ...).