Catalogue d'erreurs

Toute erreur de l'API renvoie du JSON, jamais du HTML et jamais une trace d'exécution. Le champ code est un contrat public : sa signification ne change jamais. Nous ajoutons des codes, nous n'en modifions aucun.

Forme d'une réponse d'erreur

{
  "error": {
    "code": "MISSING_PARAMETER",
    "message": "Le paramètre 'title' est requis.",
    "param": "title",
    "docs": "https://myog.dev/docs/errors#missing_parameter",
    "requestId": "req_01J8X2..."
  }
}

Le requestId est aussi renvoyé dans l'en-tête X-Request-Id. C'est ce que nous vous demanderons si vous nous signalez un problème : il nous permet de retrouver la trace exacte.

MISSING_PARAMETER

HTTP 400

Ce qui s'est passé: Un paramètre obligatoire est absent de l'URL. En pratique, c'est presque toujours `title`.
Comment corriger: Ajoutez le paramètre indiqué par le champ `param` de la réponse. `title` accepte aussi son alias court `t`.
Exemple: /v1/og?key=myog_pk_… → manque title

INVALID_PARAMETER

HTTP 400

Ce qui s'est passé: Un paramètre est présent mais sa valeur sort des bornes acceptées : titre trop long, dimension hors plage, couleur mal formée.
Comment corriger: Consultez la référence des paramètres. Le champ `param` de la réponse désigne exactement celui à corriger.
Exemple: ?title=…&w=5000 → la largeur maximale est 2000

PAYLOAD_TOO_LARGE

HTTP 400

Ce qui s'est passé: La chaîne de requête dépasse 4 Ko. Cela arrive quand un titre très long est encodé plusieurs fois de suite.
Comment corriger: Raccourcissez le titre, et vérifiez que vous n'appelez pas `encodeURIComponent` deux fois sur la même valeur.

MISSING_API_KEY

HTTP 401

Ce qui s'est passé: Aucune clé n'a été fournie, ni via le paramètre `key`, ni via l'en-tête `Authorization`.
Comment corriger: Ajoutez `&key=myog_pk_…` à votre URL. Créez une clé depuis le dashboard si vous n'en avez pas encore.

INVALID_API_KEY

HTTP 401

Ce qui s'est passé: La clé est inconnue, révoquée, ou son format ne correspond à aucun préfixe MyOG.
Comment corriger: Vérifiez que vous copiez la clé entière, préfixe compris. Une clé révoquée ne peut pas être réactivée : créez-en une nouvelle.

REFERER_NOT_ALLOWED

HTTP 403

Ce qui s'est passé: La requête vient d'un domaine absent de la liste autorisée pour cette clé publique — ou bien une clé secrète est utilisée depuis un navigateur.
Comment corriger: Ajoutez le domaine dans les réglages de la clé. Si vous appelez depuis un navigateur, utilisez une clé publique (`myog_pk_`), jamais une clé secrète.

KEY_DISABLED

HTTP 403

Ce qui s'est passé: Cette clé a été désactivée manuellement depuis le dashboard.
Comment corriger: Réactivez-la, ou basculez sur une autre clé active.

TEMPLATE_NOT_FOUND

HTTP 404

Ce qui s'est passé: Le template demandé n'existe pas.
Comment corriger: Utilisez `minimal`, `gradient`, `terminal` ou `article`. La casse compte.

RENDER_FAILED

HTTP 422

Ce qui s'est passé: Le moteur n'a pas pu produire l'image. C'est presque toujours un bug de notre côté.
Comment corriger: Nous servons une image de repli neutre plutôt qu'une erreur, pour ne pas casser votre carte sociale. Signalez-nous le `requestId` : il nous permet de retrouver la trace exacte.

RATE_LIMIT_EXCEEDED

HTTP 429

Ce qui s'est passé: Trop de requêtes par seconde sur cette clé.
Comment corriger: Respectez l'en-tête `Retry-After`. Si vous générez des images en masse, étalez les appels : le cache absorbera ensuite l'essentiel du trafic.

QUOTA_EXCEEDED

HTTP 429

Ce qui s'est passé: Le quota mensuel du compte est atteint.
Comment corriger: Sur le plan gratuit, nous servons une image de repli en 200 plutôt qu'une erreur — vos pages ne cassent pas. Passez au plan Pro pour rétablir vos visuels immédiatement.

INTERNAL_ERROR

HTTP 500

Ce qui s'est passé: Une erreur inattendue est survenue de notre côté.
Comment corriger: Réessayez. Si le problème persiste, envoyez-nous le `requestId` de la réponse.

SERVICE_DEGRADED

HTTP 503

Ce qui s'est passé: Une dépendance est momentanément indisponible et l'API fonctionne en mode dégradé.
Comment corriger: Réessayez avec un délai croissant (backoff exponentiel). Consultez la page de statut pour connaître l'état en cours.