Fouten

Foutstructuur

Alle fouten volgen dezelfde JSON-structuur:

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

Het veld error is een tekst in natuurlijke taal, geschikt om te loggen of aan gebruikers te tonen. Het veld code is een stabiele, machineleesbare identifier, bedoeld voor programmatische foutafhandeling.

HTTP-statuscodes

HTTP	Betekenis
`400`	Bad Request - misvormde JSON of ongeldige parameter
`401`	Unauthorized - ontbrekende of ongeldige API-sleutel
`403`	Forbidden - de sleutel is geldig, maar het account heeft niet het vereiste abonnement
`404`	Not Found - de resource bestaat niet of behoort tot een ander account
`422`	Unprocessable Entity - geldige JSON, maar een bedrijfsregel wordt geschonden
`429`	Too Many Requests - snelheidslimiet overschreden
`500`	Internal Server Error - onverwachte serverfout

Foutcodes

HTTP	code	Beschrijving
`401`	`MISSING_API_KEY`	Geen API-sleutel meegegeven in de aanvraag
`401`	`INVALID_API_KEY`	Sleutel niet gevonden in de database of ingetrokken
`403`	`PLAN_REQUIRED`	Het account heeft geen Agency-abonnement
`404`	`NOT_FOUND`	Resource niet gevonden of behoort niet tot het geauthenticeerde account
`422`	`VALIDATION_ERROR`	De aanvraagbody heeft de schemavalidatie niet doorstaan
`422`	`LIMIT_REACHED`	Planlimiet bereikt (bijv. maximumaantal merken)
`422`	`LIMIT_EXCEEDED`	Resourcelimiet bereikt (bijv. avatarlimiet van het abonnement)
`422`	`QUOTA_EXCEEDED`	Onvoldoende credits om de gevraagde campagne te starten
`409`	`CONFLICT`	Er bestaat al een resource met dezelfde unieke identifier
`429`	`RATE_LIMITED`	Limiet van 60 aanvr./min per sleutel overschreden
`500`	`INTERNAL_ERROR`	Onverwachte serverfout

Details over de snelheidslimiet

De limiet is 60 aanvragen per minuut per API-sleutel, gehandhaafd via een Redis-teller met een glijdend venster. Bij overschrijding:

HTTP-status: 429
Antwoordheader: Retry-After: 60
Code in de body: RATE_LIMITED

De limiter is permissief bij een storing - als Redis tijdelijk niet beschikbaar is, worden alle aanvragen toegestaan in plaats van geblokkeerd.

Foutafhandeling

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);
  }
}