Erreurs d'API — signification de chaque code et comment le corriger

FastOG renvoie des codes d'erreur lisibles par machine lorsqu'une requête échoue — un rendu d'image OG signé, ou un appel à l'une des surfaces d'administration intégrées au produit. Chaque réponse d'erreur contient :

• error — l'ancien jeton court. Toujours présent à chaque échec pour qu'un client plus ancien continue de fonctionner.
• code — le même code d'erreur stable et documenté (tableau ci-dessous), sous le nom utilisé par l'API publique.
• message — une description en une phrase de ce qui a échoué.
• hint — une courte description en langage clair de ce qui a échoué et de la façon de le corriger.
• docs_url — un lien vers cette page, ancré sur la section correspondant à ce code.
• request_id — corrèle cet échec HTTP à une ligne du tableau Render Logs du dashboard (également renvoyé dans l'en-tête de réponse X-Request-ID). Une surface sans rien à corréler répond null, mais la clé est toujours présente.

Les surfaces intégrées au produit — l'admin Shopify, le WooCommerce Studio, le pont Wix et la démo — répondent avec la même enveloppe pour les codes ci-dessous, si bien qu'un échec signifie la même chose où que vous le rencontriez. Une surface de module peut conserver le statut HTTP qu'elle a toujours renvoyé pour un code (par exemple render_failed répond 503 sur l'export de couverture et 502 sur l'API publique) ; le code, le message, l'indication et le lien vers la documentation ne changent pas.

Lire une réponse d'erreur

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

Si vous recevez une réponse que vous ne comprenez pas, voici la démarche la plus rapide :

1. Notez le code.
2. Vérifiez votre générateur d'URL — la plupart des échecs sont des bugs de signature, pas des problèmes de compte.
3. Reportez-vous au code ci-dessous pour identifier la cause exacte et le correctif.
4. Dans le tableau de bord, ouvrez Render Logs et filtrez sur le même error_code — chaque ligne affiche les paramètres demandés pour que vous puissiez reproduire le problème (et confirmer que request_id correspond).

Signature et authentification

missing_signature

Il manque à votre requête les paramètres de requête key et/ou s (signature).

Correction : assurez-vous que votre URL contient à la fois key=<api-key> et s=<hmac-signature>. Utilisez le SDK ou le guide /docs/hmac-signature-guide pour la construire.

invalid_signature

La valeur s ne correspond pas à ce que votre secret HMAC produit pour cette URL.

Correction : la signature couvre tous les paramètres de requête sauf s, avec les clés triées. Modifier un paramètre — y compris le réordonner, des différences d'encodage URL ou l'ajout d'espaces — invalide la signature. Re-signez après chaque modification. Vérifiez que votre secret est bien celui affiché lors de la création de la clé API.

invalid_signature_format

La valeur s n'est pas une chaîne hexadécimale de 64 caractères.

Correction : la signature doit être le hachage SHA-256 brut en hexadécimal (minuscules a-f0-9). Si vous encodez en base64 ou tronquez la sortie, utilisez simplement l'hexadécimal.

expired_timestamp

L'horodatage t que vous avez fourni date de plus de 5 minutes.

Correction : régénérez l'horodatage à chaque fois que vous construisez une URL. Ce code s'applique au flux hérité des URL signées ; le flux HMAC v2 actuel n'a pas d'horodatage.

invalid_api_key

La key que vous avez transmise n'existe pas.

Correction : copiez la clé API complète depuis le tableau de bord — c'est l'identifiant public commençant par sk_. Il est public et sans risque dans les URL ; c'est le secret (jamais dans les URL) qui prouve la possession.

missing_hmac_secret

Aucun secret HMAC n'est configuré pour la clé API.

Correction : créez une nouvelle clé API dans le tableau de bord — le secret HMAC est généré et affiché une seule fois à la création.

Paramètre / entrée

invalid_image_url

Une prop contenant une URL (image, brand_logo, logo, avatar, background_image, ...) n'est pas une URL http(s) publique.

Correction : passez une URL https://... accessible publiquement. Les adresses localhost, les IP privées et les chemins bruts sont rejetés afin de prévenir les falsifications de requête côté serveur (SSRF).

Abonnement

subscription_required (402)

La requête a atteint la Dynamic API, mais votre compte ne dispose d'aucun forfait actif. L'accès à l'API est réservé aux abonnés : le forfait fait office de condition d'accès et reprend la même couverture ainsi que la même progressivité des fonctionnalités que celles vendues par les applications FastOG. Les rendus eux-mêmes ne sont pas mesurés : il n'existe ni quota mensuel de rendus ni facturation au dépassement.

Correction : choisissez un forfait Dynamic API dans le dashboard et créez une clé API. La réponse inclut un top_up_url pointant vers la page des forfaits.

Service de rendu

store_blocked (403)

Le rendu pour la boutique associée à cette clé a été suspendu par FastOG (par exemple en cas d'abus ou d'usage excessif). Les couvertures déjà mises en cache au niveau du edge peuvent continuer à être servies jusqu'à leur expiration. Contactez le support pour résoudre la situation ; aucune modification de la requête ne permettra d'y remédier.

render_unreachable

Le service de rendu n'a pas pu être joint (fenêtre de redémarrage brève).

Correctif : réessayez dans quelques secondes. Le rendu n'a pas été comptabilisé pour cette tentative.

render_failed

Le service de rendu a renvoyé une erreur pour votre requête.

Correctif : vérifiez les props de votre template — valeurs trop longues ou malformées, champs non pris en charge, ou image amont inaccessible. La réponse inclut le status sous-jacent. Le rendu n'a pas été comptabilisé.

Surfaces d'administration de la boutique

Ces codes répondent depuis l'administration Shopify et le WooCommerce Studio — les éditeurs intégrés dans lesquels un marchand travaille plutôt que l'API signée. Plusieurs sont partagés avec l'API publique (invalid_image_url, render_failed, invalid_signature) ; ceux-ci conservent l'entrée documentée ci-dessus.

Passerelle Wix

La passerelle Wix est signée par l'application Wix, et non par une session marchand ; ses échecs sont donc adressés au développeur de l'application. Chaque réponse porte toujours code et request_id ; l'identifiant de requête de la passerelle est celui de l'enveloppe signée.

Surface de démonstration

La démo est la console de ventes réservée au propriétaire, et non un endpoint marchand.

Codes de l'éditeur de règles à portée limitée

Les éditeurs de règles à portée limitée (admin Shopify et WooCommerce Studio) traduisent eux-mêmes ces jetons dans la langue du marchand ; leurs réponses contiennent donc error et code mais pas hint — une seconde description en anglais ne ferait que diverger de la version localisée que le marchand voit réellement :

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.

Toujours bloqué ?

• Ouvrez la page Render Logs du tableau de bord — chaque résultat (succès et rejet) y est listé avec son error_code, le statut HTTP et les paramètres demandés.
• Exécutez php artisan og:diagnose sur une URL signée pour parcourir tout le pipeline et voir quelle étape échoue.
• Consultez la documentation dans la barre latérale pour le framework que vous utilisez (Next.js, Express, SvelteKit, ...).