Erreurs

Enveloppe d'erreur

Toutes les erreurs suivent la même structure JSON :

{
  "error": "Message lisible par un humain",
  "code": "CODE_MACHINE_LISIBLE"
}

Le champ error est une chaîne en langage naturel, adaptée à la journalisation ou à l'affichage aux utilisateurs. Le champ code est un identifiant stable lisible par une machine, destiné à la gestion programmatique des erreurs.

Codes HTTP

HTTP	Signification
`400`	Bad Request - JSON malformé ou paramètre invalide
`401`	Unauthorized - clé API manquante ou invalide
`403`	Forbidden - la clé est valide mais le compte n'a pas le plan requis
`404`	Not Found - la ressource n'existe pas ou appartient à un autre compte
`422`	Unprocessable Entity - JSON valide mais violation d'une règle métier
`429`	Too Many Requests - limite de débit dépassée
`500`	Internal Server Error - erreur inattendue côté serveur

Codes d'erreur

HTTP	code	Description
`401`	`MISSING_API_KEY`	Aucune clé API fournie dans la requête
`401`	`INVALID_API_KEY`	Clé introuvable dans la base de données ou révoquée
`403`	`PLAN_REQUIRED`	Le compte n'est pas sur le plan Agency
`404`	`NOT_FOUND`	Ressource introuvable ou n'appartenant pas au compte authentifié
`422`	`VALIDATION_ERROR`	Le corps de la requête n'a pas passé la validation de schéma
`422`	`LIMIT_REACHED`	Limite du plan atteinte (ex. nombre maximum de marques)
`422`	`LIMIT_EXCEEDED`	Limite de ressource atteinte (ex. maximum 5 avatars par marque)
`422`	`QUOTA_EXCEEDED`	Crédits insuffisants pour lancer la campagne demandée
`409`	`CONFLICT`	Une ressource avec le même identifiant unique existe déjà
`429`	`RATE_LIMITED`	Limite de 60 req/min par clé dépassée
`500`	`INTERNAL_ERROR`	Erreur inattendue côté serveur

Détails de la limitation de débit

La limite est de 60 requêtes par minute par clé API, appliquée via un compteur à fenêtre glissante Redis. En cas de dépassement :

Code HTTP : 429
En-tête de réponse : Retry-After: 60
Code dans le corps : RATE_LIMITED

Le limiteur est permissif en cas de panne - si Redis est temporairement indisponible, toutes les requêtes sont autorisées plutôt que bloquées.

Gestion des erreurs

const res = await fetch("https://mentova.ai/api/v1/brands", {
  headers: { "X-API-Key": "mtv_live_votre_cle" },
});

if (!res.ok) {
  const { error, code } = await res.json();

  if (res.status === 429) {
    const retryAfter = res.headers.get("Retry-After");
    console.error(`Limite de débit atteinte. Réessayez dans ${retryAfter}s`);
  } else if (code === "QUOTA_EXCEEDED") {
    console.error("Crédits insuffisants :", error);
  } else {
    console.error(`Erreur API [${code}] :`, error);
  }
}