Errori API — Cosa significa ogni codice e come risolverlo

FastOG restituisce codici di errore leggibili dalla macchina quando una richiesta fallisce — il rendering di un'immagine OG firmata, o una chiamata a una delle superfici di amministrazione integrate nel prodotto. Ogni risposta di errore include:

• error — il vecchio token breve. È ancora presente su ogni errore, così un client più vecchio continua a funzionare.
• code — lo stesso codice di errore stabile e documentato (tabella sotto), con il nome usato dall'API pubblica.
• message — una descrizione in una frase di cosa è andato storto.
• hint — una breve descrizione in linguaggio semplice di cosa è andato storto e di come risolverlo.
• docs_url — un link a questa pagina, ancorato alla sezione di quel codice.
• request_id — correla questo errore HTTP a una riga nella tabella Render Logs della dashboard (restituito anche nell'header di risposta X-Request-ID). Una superficie che non ha nulla da correlare risponde null, ma la chiave è sempre presente.

Le superfici integrate nel prodotto — l'admin di Shopify, il WooCommerce Studio, il bridge Wix e la demo — rispondono con lo stesso envelope per i codici qui sotto, quindi un errore significa la stessa cosa ovunque lo incontri. Una superficie di un modulo può mantenere lo status HTTP che ha sempre restituito per un codice (ad esempio render_failed risponde 503 sull'export della copertina e 502 sull'API pubblica); il codice, il messaggio, il suggerimento e il link alla documentazione non cambiano.

Leggere una risposta di errore

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

Se ricevi una risposta che non capisci, la via più rapida è:

1. Annota il code.
2. Controlla il tuo URL builder — la maggior parte dei fallimenti sono bug di firma, non problemi di account.
3. Confronta il codice qui sotto per la causa esatta e la correzione.
4. Nella dashboard, apri Render Logs e filtra per lo stesso error_code — ogni riga mostra i parametri richiesti così puoi riprodurre (e confermare che request_id corrisponda).

Firma e autenticazione

missing_signature

Alla tua richiesta mancano i parametri di query key e/o s (firma).

Correzione: assicurati che il tuo URL includa sia key=<api-key> che s=<hmac-signature>. Usa l'SDK o la guida /docs/hmac-signature-guide per costruirlo.

invalid_signature

Il valore s non corrisponde a quello prodotto dal tuo HMAC secret per questo URL.

Correzione: la firma copre tutti i parametri di query tranne s, con le chiavi ordinate. Modificare qualsiasi parametro — incluso il riordino, differenze nella codifica URL o l'aggiunta di spazi — invalida la firma. Firma di nuovo dopo ogni modifica. Verifica che il tuo secret sia lo stesso mostrato al momento della creazione della API key.

invalid_signature_format

Il valore s non è una stringa esadecimale di 64 caratteri.

Correzione: la firma deve essere l'hex grezzo dello SHA-256 (minuscolo a-f0-9). Se stai codificando in base64 o troncando l'output, usa l'hex semplice.

expired_timestamp

Il timestamp t che hai fornito ha più di 5 minuti.

Correzione: rigenera il timestamp ogni volta che costruisci un URL. Questo codice si applica al flusso legacy degli URL firmati; il flusso HMAC v2 attuale non ha timestamp.

invalid_api_key

La key che hai passato non esiste.

Correzione: copia la API key completa dalla dashboard — è l'identificatore pubblico che inizia con sk_. È pubblica e sicura negli URL; il secret (mai negli URL) è ciò che prova il possesso.

missing_hmac_secret

La API key non ha un HMAC secret configurato.

Correzione: crea una nuova API key nella dashboard — l'HMAC secret viene generato e mostrato una sola volta alla creazione.

Parametro / input

invalid_image_url

Una prop che contiene un URL (image, brand_logo, logo, avatar, background_image, ...) non è un URL http(s) pubblico.

Correzione: passa un URL https://... recuperabile pubblicamente. Localhost, IP privati e percorsi senza host vengono rifiutati per prevenire il server-side request forgery.

Abbonamento

subscription_required (402)

La richiesta ha raggiunto la Dynamic API ma il tuo account non ha un piano attivo. L'accesso all'API è solo tramite abbonamento: il piano è il requisito, e offre la stessa copertura e la stessa scala di funzionalità vendute dalle app FastOG. I render stessi non sono misurati: non esiste una quota mensile di render né una fatturazione per eccedenza.

Correzione: scegli un piano Dynamic API nella dashboard e crea una chiave API. La risposta include un top_up_url che punta alla pagina dei piani.

Servizio di rendering

store_blocked (403)

Il rendering per lo store associato a questa chiave è stato sospeso da FastOG (ad esempio per abuso o utilizzo eccessivo). Le copie già in cache all'edge possono continuare a essere servite fino alla scadenza. Contatta il supporto per risolvere la situazione; nessuna modifica che puoi apportare alla richiesta risolverà il problema.

render_unreachable

Non è stato possibile raggiungere il servizio di rendering (breve finestra di riavvio).

Correzione: riprova tra qualche secondo. Il rendering non è stato conteggiato per questo tentativo.

render_failed

Il servizio di rendering ha restituito un errore per la tua richiesta.

Correzione: verifica le props del tuo template — valori lunghi o malformati, campi non supportati o un'immagine upstream non raggiungibile. La risposta include il status sottostante. Il rendering non è stato conteggiato.

Superfici di amministrazione dello store

Questi codici rispondono dall'admin di Shopify e da WooCommerce Studio — gli editor integrati in cui lavora un merchant piuttosto che l'API firmata. Diversi sono condivisi con l'API pubblica (invalid_image_url, render_failed, invalid_signature); per quelli resta valida la voce documentata sopra.

Bridge Wix

Il bridge Wix è firmato dall'app Wix, non da una sessione del merchant, quindi i suoi errori sono indirizzati allo sviluppatore dell'app. Ogni risposta porta comunque code e request_id; l'id della richiesta del bridge è quello dell'envelope firmato.

Superficie della demo

La demo è la console di vendita riservata al proprietario, non un endpoint per i merchant.

Codici dell'editor delle regole con ambito

Gli editor delle regole con ambito (admin di Shopify e WooCommerce Studio) traducono questi token autonomamente, nella lingua del merchant, quindi le loro risposte contengono error e code ma non hint — una seconda descrizione in inglese finirebbe solo per divergere da quella localizzata che il merchant vede effettivamente:

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.

Ancora bloccato?

• Apri la pagina Render Logs della dashboard — ogni esito (successo + rifiuto) è elencato con il suo error_code, lo stato HTTP e i parametri richiesti.
• Esegui php artisan og:diagnose su un URL firmato per percorrere l'intera pipeline e vedere quale fase fallisce.
• Consulta la documentazione nella barra laterale per il framework che stai usando (Next.js, Express, SvelteKit, ...).