Codes d'Erreur

Comprendre les réponses d'erreur de l'API et comment les gérer.

Aperçu

L'API renvoie des réponses d'erreur standardisées avec des codes d'erreur spécifiques pour vous aider à identifier et résoudre rapidement les problèmes.

Format de la Réponse d'Erreur

Toutes les réponses d'erreur suivent cette structure :

{
  "status": "error",
  "error": {
    "code": "AUTH_1001",
    "message": "Identifiants d'authentification manquants",
    "details": "Les champs 'username' et 'password' sont tous deux requis",
    "timestamp": "2025-12-22T10:30:00Z"
  }
}

Champ	Type	Description
`status`	string	Toujours "error" pour les réponses d'erreur
`error.code`	string	Identifiant unique de l'erreur
`error.message`	string	Message d'erreur lisible
`error.details`	string	Contexte supplémentaire (optionnel)
`error.timestamp`	string	Horodatage ISO 8601

Erreurs d'Authentification (1000-1099)

Erreurs liées aux identifiants et à l'authentification.

Code	HTTP	Message	Solution
`AUTH_1001`	401	Identifiants d'authentification manquants	Incluez le nom d'utilisateur et le mot de passe dans la requête
`AUTH_1002`	401	Nom d'utilisateur ou mot de passe invalide	Vérifiez que les identifiants sont corrects
`AUTH_1003`	403	Compte temporairement verrouillé	Attendez avant de réessayer ou contactez le support

Erreurs de Quota (1100-1199)

Erreurs liées au quota API et aux limites d'utilisation.

Code	HTTP	Message	Solution
`QUOTA_1101`	403	Quota API insuffisant	Achetez plus de crédits ou vérifiez le quota
`QUOTA_1102`	429	Quota API dépassé	Attendez le renouvellement du quota ou mettez à niveau votre plan

Erreurs de Validation (2000-2099)

Erreurs liées à la validation de la requête et aux données d'entrée.

Code	HTTP	Message	Solution
`VAL_2001`	400	Aucun fichier téléchargé	Incluez un fichier dans la requête
`VAL_2002`	400	Format de fichier invalide	Utilisez les formats supportés : PDF, PNG, JPG, WEBP
`VAL_2003`	400	Plusieurs fichiers PDF non autorisés	Téléchargez un seul PDF ou plusieurs images
`VAL_2004`	400	PDF et images ne peuvent pas être mélangés	Téléchargez soit un PDF soit des images, pas les deux
`VAL_2005`	400	Code de langue non supporté	Utilisez un code de langue supporté

Erreurs de Traitement (3000-3099)

Erreurs lors du traitement du document et de l'analyse IA.

Code	HTTP	Message	Solution
`PROC_3001`	500	Échec du traitement du document	Vérifiez la qualité de l'image, réessayez la requête
`PROC_3002`	500	Échec de l'extraction des métadonnées	Assurez-vous que le document contient du texte lisible
`PROC_3003`	500	Échec de l'extraction des paramètres	Vérifiez que le format de l'analyse sanguine est reconnaissable
`PROC_3004`	500	Échec de la génération de l'interprétation	Réessayez la requête
`PROC_3006`	504	Délai de traitement dépassé	Réduisez la taille du fichier ou divisez en plusieurs requêtes
`PROC_3007`	500	Analyse échouée après plusieurs tentatives	Attendez et réessayez, ou contactez le support

Erreurs Serveur (5000-5099)

Erreurs internes du serveur et problèmes de disponibilité du service.

Code	HTTP	Message	Solution
`SRV_5001`	500	Erreur interne du serveur	Réessayez la requête, contactez le support si le problème persiste
`SRV_5002`	503	Service temporairement indisponible	Attendez et réessayez avec un backoff exponentiel

Bonnes Pratiques de Gestion des Erreurs

Recommandations

Vérifiez toujours le champ status - Les réponses réussies ont "status": "success"
Implémentez une logique de réessai pour les erreurs transitoires (5xx) avec backoff exponentiel
Enregistrez les codes d'erreur pour le débogage et la surveillance
Affichez des messages conviviaux basés sur les codes d'erreur
Utilisez les points d'accès sandbox pour tester la gestion des erreurs

Exemple de Gestion des Erreurs (JavaScript)

async function analyzeBloodTest(file) {
  try {
    const response = await fetch(API_URL, {
      method: 'POST',
      body: formData
    });

    const data = await response.json();

    if (data.status === 'error') {
      const errorCode = data.error.code;

      switch (true) {
        case errorCode.startsWith('AUTH_'):
          throw new Error('Échec de l\'authentification. Vérifiez vos identifiants.');
        case errorCode.startsWith('QUOTA_'):
          throw new Error('Quota dépassé. Veuillez mettre à niveau votre plan.');
        case errorCode.startsWith('VAL_'):
          throw new Error('Requête invalide : ' + data.error.message);
        case errorCode.startsWith('PROC_'):
          // Réessayer pour les erreurs de traitement
          return retryRequest(file);
        default:
          throw new Error('Une erreur s\'est produite. Veuillez réessayer.');
      }
    }

    return data.data;
  } catch (error) {
    console.error('Erreur API :', error);
    throw error;
  }
}