Codes d'erreur

Toutes les erreurs de l'API suivent un format cohérent. Le code de statut HTTP indique la catégorie de l'erreur, et le corps de la réponse contient un code d'erreur lisible par une machine ainsi qu'un message lisible par un humain.

Format des erreurs

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Company not found for KVK number 99999999"
  }
}

Codes d'erreur

Validation de TVA pendant une panne de VIES

VIES est une passerelle vers le service de TVA propre à chaque État membre, et ces services tombent parfois en panne. Lorsqu'un État membre est indisponible, VIES répond par un HTTP 200 sans aucun verdict. Nous ne le transformons jamais en "valid": false, car un client le lirait comme « ce numéro de TVA est invalide » et rejetterait à tort une contrepartie parfaitement légitime.

À la place, /v1/validate/vat/{vatNumber} vous indique dans laquelle des quatre situations vous vous trouvez grâce à un champ status. Trois d'entre elles renvoient un 200, seule la dernière renvoie un 502.

Chaque réponse contient aussi checksumValid, le résultat de l'elfproef néerlandais sur le bloc de neuf chiffres. Il vaut true lorsque le numéro est bien formé, ce qui n'est pas la même chose que valide : le contrôle écarte les fautes de frappe et les chiffres inversés, mais un nombre à neuf chiffres choisi au hasard le réussit tout de même environ une fois sur onze. Il ne dit rien sur l'enregistrement ou l'activité du numéro. Seul VIES y répond. Pour un numéro non néerlandais, il vaut null, car chaque État membre applique son propre schéma.

{
  "vatNumber": "NL123456789B01",
  "valid": true,
  "name": "Acme B.V.",
  "address": "Herengracht 100, 1015 AA Amsterdam",
  "validatedAt": "2026-08-14T09:12:00Z",
  "status": "stale",
  "ageSeconds": 786240,
  "checksumValid": true,
  "unavailableReason": "MS_UNAVAILABLE"
}

Les mêmes champs status, checksumValid et ageSeconds figurent dans l'objet vat d'une recherche d'entreprise, avec une quatrième valeur, unvalidated, pour un numéro de TVA candidat déduit que VIES n'a jamais confirmé. Dans ce cas, valid vaut null.

Gérer les erreurs

Nous recommandons de vérifier d'abord le code de statut HTTP, puis d'analyser le corps de l'erreur pour obtenir plus de détails :

const res = await fetch("https://api.kvkbase.nl/v1/lookup/12345678", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});

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

  switch (error.code) {
    case "NOT_FOUND":
      console.log("Entreprise introuvable");
      break;
    case "RATE_LIMIT_EXCEEDED":
      // Patienter puis réessayer
      const retryAfter = res.headers.get("Retry-After");
      break;
    case "QUOTA_EXCEEDED":
      console.log("Quota mensuel atteint");
      break;
    default:
      console.error("Erreur d'API :", error.message);
  }
}

En-têtes de limite de débit

Chaque réponse contient des informations sur la limite de débit dans ses en-têtes :