Gestion des erreurs

L'API NERP Suite utilise des codes HTTP standards et retourne des messages d'erreur détaillés pour vous aider à diagnostiquer les problèmes.

Format des erreurs

Toutes les erreurs suivent ce format JSON :

{
  "statusCode": 400,
  "message": "Description de l'erreur",
  "error": "Bad Request"
}

Codes d'erreur HTTP

Erreurs client (4xx)

Erreurs serveur (5xx)

Erreurs courantes

Authentification

// Clé API manquante
{
  "statusCode": 401,
  "message": "API key is required",
  "error": "Unauthorized"
}

// Clé API invalide
{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}

// Clé révoquée
{
  "statusCode": 401,
  "message": "API key has been revoked",
  "error": "Unauthorized"
}

Permissions

// Scope manquant
{
  "statusCode": 403,
  "message": "Insufficient scopes. Required: read:products",
  "error": "Forbidden"
}

// Aucun plan Essential actif
{
  "statusCode": 403,
  "errorCode": "PLAN_REQUIRED",
  "message": "An active Essential plan is required",
  "error": "Forbidden"
}

Ressources

// Produit non trouvé
{
  "statusCode": 404,
  "message": "Product not found",
  "error": "Not Found"
}

// Client non trouvé
{
  "statusCode": 404,
  "message": "Customer not found",
  "error": "Not Found"
}

Validation

// Données invalides
{
  "statusCode": 400,
  "message": [
    "email must be a valid email",
    "phone must be a valid phone number"
  ],
  "error": "Bad Request"
}

// Stock insuffisant
{
  "statusCode": 422,
  "message": "Insufficient stock for product PROD-123",
  "error": "Unprocessable Entity"
}

Bonnes pratiques

1. Gérez toutes les erreurs

async function callApi(endpoint) {
  const response = await fetch(`https://api.nerpsuite.com/v1/public-api${endpoint}`, {
    headers: { 'X-API-Key': process.env.API_KEY }
  });

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

    switch (response.status) {
      case 401:
        throw new Error('Vérifiez votre clé API');
      case 403:
        throw new Error('Permission insuffisante');
      case 404:
        throw new Error('Ressource non trouvée');
      case 429:
        throw new Error('Trop de requêtes, réessayez plus tard');
      default:
        throw new Error(error.message || 'Erreur inconnue');
    }
  }

  return response.json();
}

2. Loguez les erreurs pour le debugging

Conservez le statusCode, le message et le timestamp pour faciliter le diagnostic.

3. Montrez des messages utilisateur appropriés

Ne montrez jamais les messages d'erreur bruts de l'API aux utilisateurs finaux. Traduisez-les en messages compréhensibles.

4. Implémentez des retries intelligents

Les erreurs 5xx et 429 peuvent être retentées avec un backoff exponentiel. Les erreurs 4xx (sauf 429) ne doivent pas être retentées sans correction.

Support

Si vous rencontrez des erreurs persistantes ou inexpliquées :

1. Vérifiez le statut du service
2. Consultez les logs de votre application
3. Contactez le support avec le code d'erreur et l'heure exacte