Gestion des erreurs

L’API Chariow utilise des codes de réponse HTTP conventionnels pour indiquer le succès ou l’échec des requêtes.

Format de réponse

Toutes les réponses de l’API suivent un format cohérent :

{
  "message": "Message de succès ou description de l'erreur",
  "data": {},
  "errors": []
}

Les réponses d’erreur contiennent toujours message et errors. Certaines d’entre elles, comme les erreurs d’authentification et de limite de débit, omettent le champ data.

Codes de statut HTTP

Code	Description
`200`	Succès - Requête traitée avec succès
`201`	Créé - Ressource créée avec succès
`400`	Requête incorrecte - Paramètres invalides
`401`	Non autorisé - Clé API invalide ou manquante
`403`	Interdit - La clé API ne possède pas un scope exigé par l’endpoint
`404`	Non trouvé - La ressource n’existe pas
`422`	Entité non traitable - Échec de la validation
`429`	Trop de requêtes - Limite de débit atteinte
`500`	Erreur interne du serveur - Un problème est survenu

Erreurs courantes

Erreurs d’authentification (401)

Ces messages sont toujours renvoyés en anglais :

{
  "message": "API key is missing. Please provide a valid API key. Help: https://docs.chariow.com",
  "errors": []
}

Message	Cause
`API key is missing. Please provide a valid API key. Help: https://docs.chariow.com`	En-tête `Authorization: Bearer` manquant
`Invalid API key. Please check again. Help: https://docs.chariow.com`	Clé mal formée ou supprimée, ou clé dont le créateur n’est plus un membre actif de l’équipe

Solution :

# Assurez-vous d'inclure l'en-tête Authorization
curl -X GET "https://api.chariow.com/v1/store" \
  -H "Authorization: Bearer VOTRE_CLE_API"

Scope manquant (403)

La clé API est valide mais ne possède pas un scope exigé par l’endpoint :

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="checkout.write"

{
  "message": "Il manque à cet identifiant le scope requis : checkout.write. Modifiez ses permissions depuis votre tableau de bord.",
  "data": [],
  "errors": {
    "scopes": ["checkout.write"]
  }
}

Causes :

La clé a été créée sans le scope exigé par l’endpoint
Le rôle du membre de l’équipe qui a créé la clé a été rétrogradé, ce qui a retiré le scope

Solution : ajoutez les scopes listés dans errors.scopes à la clé dans Paramètres → Clés API. Lisez errors.scopes plutôt que message dans votre code, car le message est traduit dans la langue de la requête. Consultez Authentification pour connaître le scope exigé par chaque endpoint.

Ressource non trouvée (404)

{
  "message": "No query results for model [App\\Models\\Product].",
  "data": [],
  "errors": []
}

Causes :

ID de ressource invalide
La ressource appartient à une autre boutique
La ressource a été supprimée
Le produit n’est pas publié (pour les endpoints publics)

Erreurs de validation (422)

{
  "message": "The email field is required. (and 1 more error)",
  "data": [],
  "errors": {
    "email": ["The email field is required."],
    "product_id": ["The selected product_id is invalid."]
  }
}

Causes :

Champs obligatoires manquants
Format de champ invalide
Non-respect d’une règle métier

Limite de débit dépassée (429)

{
  "message": "Too Many Attempts.",
  "errors": []
}

Solution : attendez le nombre de secondes indiqué dans l’en-tête Retry-After, puis réessayez. Consultez Limites de débit pour plus de détails.

Exemple en JavaScript

async function makeRequest(endpoint, options = {}) {
  const response = await fetch(`https://api.chariow.com/v1${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
      ...options.headers
    }
  });

  const data = await response.json();

  if (!response.ok) {
    switch (response.status) {
      case 401:
        throw new AuthenticationError(data.message);
      case 403:
        throw new MissingScopeError(data.message, data.errors.scopes);
      case 404:
        throw new NotFoundError(data.message);
      case 422:
        throw new ValidationError(data.message, data.errors);
      case 429:
        throw new RateLimitError(data.message);
      default:
        throw new ApiError(data.message, response.status);
    }
  }

  return data;
}

// Utilisation
try {
  const product = await makeRequest('/products/prd_abc123');
  console.log(product);
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Produit non trouvé');
  } else if (error instanceof ValidationError) {
    console.log('Échec de la validation :', error.errors);
  } else {
    console.error('Erreur API :', error.message);
  }
}

Exemple en PHP

<?php

function makeRequest($endpoint, $method = 'GET', $data = null) {
    $ch = curl_init();

    curl_setopt($ch, CURLOPT_URL, "https://api.chariow.com/v1{$endpoint}");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . getenv('CHARIOW_API_KEY'),
        'Content-Type: application/json'
    ]);

    if ($method === 'POST') {
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    }

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $result = json_decode($response, true);

    if ($httpCode >= 400) {
        throw new Exception($result['message'], $httpCode);
    }

    return $result;
}

// Utilisation
try {
    $product = makeRequest('/products/prd_abc123');
    print_r($product);
} catch (Exception $e) {
    if ($e->getCode() === 404) {
        echo "Produit non trouvé\n";
    } else {
        echo "Erreur API : " . $e->getMessage() . "\n";
    }
}

Référence des codes d’erreur

Erreurs de paiement

Message	Cause	Solution
`Product not found. Please verify the product ID and ensure it is published.`	ID de produit invalide ou produit non publié	Utilisez l’ID d’un produit valide et publié
`Already purchased`	Le client possède déjà ce produit	Redirigez-le vers son achat
`Product unavailable`	Rupture de stock ou limite de quantité	Vérifiez la disponibilité du produit
`Invalid discount code`	Le code n’existe pas ou a expiré	Vérifiez le code de réduction

Erreurs de licence

Message	Cause	Solution
`License key not found.`	Clé de licence invalide	Vérifiez la clé de licence
`Activation limit reached`	Toutes les activations sont utilisées	Montrez à l’utilisateur ses activations
`License has expired`	Date d’expiration dépassée	Proposez un renouvellement
`License has been revoked`	Révoquée manuellement	Contactez le support
`License has already been revoked`	Révocation d’une licence déjà révoquée	Aucune action nécessaire

Bonnes pratiques

Toujours vérifier le code de statut

Ne présumez jamais qu’une requête a réussi : vérifiez toujours le code de statut HTTP avant de traiter la réponse.

Journaliser les erreurs

Conservez les réponses d’erreur pour le débogage et la surveillance.

Afficher des messages clairs

Traduisez les erreurs de l’API en messages compréhensibles pour vos clients.

Implémenter des réessais

Pour les erreurs 5xx et les limites de débit, implémentez une logique de réessai avec backoff exponentiel.

Introduction

Guides

Intégration MCP

Intégration n8n

Resources

Gestion des erreurs

Format de réponse

Codes de statut HTTP

Erreurs courantes

Erreurs d’authentification (401)

Scope manquant (403)

Ressource non trouvée (404)

Erreurs de validation (422)

Limite de débit dépassée (429)