Codes d'erreur
L'API v2 utilise les codes HTTP standards pour indiquer le succes ou l'echec d'une requete. Chaque reponse d'erreur suit le format uniforme avec success: false et un message explicatif.
Codes HTTP
| Code | Statut | Description |
|---|---|---|
400 | Bad Request | Parametres invalides ou champs obligatoires manquants dans la requete. |
401 | Unauthorized | Cle API manquante, invalide ou couple API Key / API Secret incorrect. |
402 | Payment Required | Abonnement inactif ou expire. Renouvelez votre souscription pour continuer. |
404 | Not Found | La ressource demandee n'existe pas (entreprise, etablissement, webhook, etc.). |
429 | Too Many Requests | Limite de debit horaire ou quota mensuel depasse. Reessayez apres le delai indique. |
500 | Internal Server Error | Erreur interne du serveur. Si le probleme persiste, contactez le support. |
502 | Bad Gateway | Service en amont indisponible (ex. VIES pour la validation TVA, BCE/KBO). |
Exemples de reponses d'erreur
400 — Parametres invalides
Se produit lorsqu'un parametre obligatoire est manquant ou que la valeur fournie est invalide (ex. numero d'entreprise mal forme).
{
"success": false,
"error": "Invalid enterprise number format. Expected 10 digits.",
"timestamp": "2026-04-17T12:00:00.000Z"
}401 — Authentification manquante ou invalide
Se produit lorsque les en-tetes X-API-Key et/ou X-API-Secret sont absents ou incorrects.
{
"success": false,
"error": "Invalid or missing API key",
"timestamp": "2026-04-17T12:00:00.000Z"
}402 — Abonnement inactif
Se produit lorsque votre abonnement est expire ou suspendu. Renouvelez votre plan depuis le tableau de bord.
{
"success": false,
"error": "Subscription inactive. Please renew your plan.",
"timestamp": "2026-04-17T12:00:00.000Z"
}404 — Ressource introuvable
Se produit lorsque l'entreprise, l'etablissement ou le webhook demande n'existe pas dans la base de donnees.
{
"success": false,
"error": "Enterprise not found",
"timestamp": "2026-04-17T12:00:00.000Z"
}429 — Limite de debit depassee
Se produit lorsque vous depassez la limite horaire ou le quota mensuel de votre plan. Consultez les en-tetes X-RateLimit-Reset pour savoir quand reessayer.
{
"success": false,
"error": "Rate limit exceeded. Please try again later.",
"timestamp": "2026-04-17T12:00:00.000Z"
}500 — Erreur interne
Erreur inattendue cote serveur. Si le probleme se reproduit, contactez le support a developers@espero-soft.com.
{
"success": false,
"error": "Internal server error",
"timestamp": "2026-04-17T12:00:00.000Z"
}502 — Service en amont indisponible
Se produit lorsqu'un service externe (VIES pour la validation TVA, BCE/KBO) est temporairement indisponible. Reessayez apres quelques secondes.
{
"success": false,
"error": "VIES service is temporarily unavailable. Please try again later.",
"timestamp": "2026-04-17T12:00:00.000Z"
}Gestion des erreurs
Verifiez toujours le champ success de la reponse et adaptez votre logique en fonction du code HTTP retourne.
async function callV2Api(endpoint) {
const response = await fetch(
`https://companybelgium.be/api/v2/${endpoint}`,
{
headers: {
'X-API-Key': process.env.API_KEY,
'X-API-Secret': process.env.API_SECRET,
},
}
);
const data = await response.json();
if (!data.success) {
switch (response.status) {
case 400:
console.error('Parametres invalides:', data.error);
break;
case 401:
console.error('Cle API invalide ou manquante');
break;
case 402:
console.error('Abonnement inactif — renouvelez votre plan');
break;
case 404:
console.error('Ressource introuvable:', data.error);
break;
case 429:
const resetAt = response.headers.get('X-RateLimit-Reset');
console.error(`Limite atteinte, reessayez apres ${resetAt}`);
break;
case 502:
console.error('Service externe indisponible, reessayez plus tard');
break;
default:
console.error('Erreur:', data.error);
}
return null;
}
return data.data;
}