Erreurs API courantes

Cet article vous aidera à comprendre les erreurs API les plus courantes qui peuvent être rencontrées lors de l'utilisation de la plateforme cloud EKB. Vous trouverez des détails sur les différents codes de statut HTTP et codes d'erreur spécifiques, vous fournissant les étapes essentielles de dépannage pour résoudre ces problèmes efficacement. En comprenant le format de réponse d'erreur et les pièges courants associés à l'utilisation de l'API, vous serez mieux équipé pour gérer les erreurs et améliorer votre expérience de développement.

Format de réponse d'erreur

Toutes les erreurs API suivent un format cohérent :

{
  "status_code": 400,
  "error": {
    "code": "ERROR_CODE",
    "message": "Message d'erreur lisible par l'humain"
  },
  "detail": "Détails d'erreur supplémentaires (optionnel)"
}

Certaines erreurs peuvent également inclure :

• error_id : Identifiant unique pour le suivi de l'erreur
• invalid_fields : Liste des champs qui ont échoué la validation (pour les erreurs de validation)

Codes de statut HTTP

400 Requête incorrecte

Erreurs côté client dues à une entrée invalide ou à des requêtes mal formées.

VALIDATION_ERROR

Code d'erreur : VALIDATION_ERROR Code de statut : 400

Description : La validation de la requête a échoué. Un ou plusieurs champs de la requête sont invalides.

Causes courantes :

• Champs obligatoires manquants
• Format de champ invalide (p. ex., e-mail invalide, format de date)
• Valeurs de champs en dehors de la plage autorisée
• Types de données invalides

Exemple de réponse :

{
  "status_code": 400,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Données d'entrée invalides",
    "invalid_fields": ["email", "project_id"]
  }
}

Dépannage :

1. Examinez le tableau invalid_fields pour identifier les champs problématiques
2. Vérifiez les exigences des champs dans la documentation de l'API
3. Vérifiez que les types de données correspondent aux formats attendus
4. Assurez-vous que tous les champs obligatoires sont fournis

INVALID_API_KEY

Code d'erreur : INVALID_API_KEY
Code de statut : 400

Description : La clé API fournie est invalide ou mal formée.

Dépannage :

1. Vérifiez que la clé API est correctement copiée (pas d'espaces supplémentaires)
2. Vérifiez si la clé API est active dans Mon compte > Clés API
3. Assurez-vous que vous utilisez la clé API correcte pour votre environnement
4. Régénérez la clé API si nécessaire

INVALID_CREDENTIALS

Code d'erreur : INVALID_CREDENTIALS
Code de statut : 400

Description : Les identifiants d'authentification sont invalides.

Dépannage :

1. Vérifiez que l'e-mail et le mot de passe sont corrects
2. Vérifiez si le compte est verrouillé ou désactivé
3. Essayez de réinitialiser votre mot de passe
4. Assurez-vous que vous utilisez la méthode d'authentification correcte

INVALID_OR_EXPIRED_JWT_TOKEN

Code d'erreur : INVALID_OR_EXPIRED_JWT_TOKEN
Code de statut : 400

Description : Le jeton JWT est invalide, expiré ou mal formé.

Dépannage :

1. Actualisez votre jeton d'authentification
2. Déconnectez-vous et reconnectez-vous
3. Vérifiez l'heure d'expiration du jeton
4. Vérifiez que le jeton est envoyé dans le format d'en-tête correct

401 Non autorisé

Authentification requise ou authentification échouée.

AUTHENTICATION

Code d'erreur : AUTHENTICATION
Code de statut : 401

Description : L'authentification est requise pour accéder à cette ressource.

Dépannage :

1. Assurez-vous que vous êtes connecté
2. Vérifiez si votre session a expiré
3. Vérifiez que les en-têtes d'authentification sont inclus dans la requête
4. Réauthentifiez-vous si nécessaire

INVALID_BEARER_TOKEN

Code d'erreur : INVALID_BEARER_TOKEN
Code de statut : 401

Description : Le jeton Bearer fourni est invalide.

Dépannage :

1. Vérifiez le format du jeton : Bearer <token>
2. Vérifiez si le jeton a expiré
3. Régénérez le jeton d'authentification
4. Assurez-vous que le jeton n'est pas révoqué

EMAIL_IS_NOT_VERIFIED

Code d'erreur : EMAIL_IS_NOT_VERIFIED
Code de statut : 401

Description : L'adresse e-mail n'a pas été vérifiée.

Dépannage :

1. Vérifiez votre e-mail pour le lien de vérification
2. Demandez un nouvel e-mail de vérification
3. Vérifiez que l'adresse e-mail est correcte
4. Vérifiez le dossier spam/indésirable

403 Interdit

Accès refusé en raison de permissions insuffisantes.

AUTHORIZATION

Code d'erreur : AUTHORIZATION
Code de statut : 403

Description : Vous n'avez pas la permission d'effectuer cette action.

Dépannage :

1. Vérifiez que vous avez le rôle/les permissions requises
2. Vérifiez que vous êtes un membre du projet/équipe
3. Contactez l'administrateur du projet/équipe pour accorder l'accès
4. Assurez-vous que vous accédez à la ressource correcte

PERMISSION_DENIED

Code d'erreur : PERMISSION_DENIED
Code de statut : 403

Description : Permission refusée pour l'opération demandée.

Dépannage :

1. Examinez votre rôle utilisateur et vos permissions
2. Vérifiez les paramètres d'accès du projet/équipe
3. Vérifiez la propriété des ressources
4. Contactez l'administrateur pour l'accès

DOMAIN_NOT_ALLOWED

Code d'erreur : DOMAIN_NOT_ALLOWED
Code de statut : 403

Description : Votre domaine de courrier électronique n'est pas autorisé pour cette opération.

Dépannage :

1. Vérifiez que votre domaine de courrier électronique est sur liste blanche
2. Contactez l'administrateur pour ajouter votre domaine
3. Utilisez une adresse e-mail autorisée

404 Non trouvé

La ressource demandée n'existe pas.

ENTITY_NOT_FOUND

Code d'erreur : ENTITY_NOT_FOUND
Code de statut : 404

Description : La ressource demandée n'a pas été trouvée.

Scénarios courants :

• Projet non trouvé
• Agent non trouvé
• Document non trouvé
• Utilisateur non trouvé

Dépannage :

1. Vérifiez que l'ID de la ressource est correct
2. Vérifiez si la ressource a été supprimée
3. Assurez-vous que vous avez accès à la ressource
4. Vérifiez que vous utilisez le projet/espace de travail correct

FILE_NOT_FOUND

Code d'erreur : FILE_NOT_FOUND
Code de statut : 404

Description : Le fichier demandé n'existe pas.

Dépannage :

1. Vérifiez que l'ID ou le chemin du fichier est correct
2. Vérifiez si le fichier a été supprimé
3. Assurez-vous que le fichier est à l'emplacement attendu
4. Vérifiez les permissions du fichier

FLOW_NOT_FOUND

Code d'erreur : FLOW_NOT_FOUND
Code de statut : 404

Description : Le flux/workflow demandé n'a pas été trouvé.

Dépannage :

1. Vérifiez que l'ID du flux est correct
2. Vérifiez si le flux a été supprimé
3. Assurez-vous que vous avez accès au flux
4. Vérifiez que le flux existe dans le projet actuel

CONFIG_NOT_FOUND

Code d'erreur : CONFIG_NOT_FOUND
Code de statut : 404

Description : La configuration requise n'a pas été trouvée.

Dépannage :

1. Vérifiez que la configuration existe
2. Vérifiez la configuration dans les paramètres
3. Assurez-vous que les services requis sont configurés
4. Consultez la documentation de configuration

500 Erreur interne du serveur

Erreurs côté serveur nécessitant une investigation.

ENGINE_OPERATION_FAILURE

Code d'erreur : ENGINE_OPERATION_FAILURE
Code de statut : 500

Description : Une opération interne du moteur a échoué.

Dépannage :

1. Relancez la requête après quelques instants
2. Vérifiez l'état du système sur status.getodin.ai
3. Si le problème persiste, contactez le support avec les détails de l'erreur
4. Fournissez l'ID d'erreur si disponible

EXTERNAL_SERVICE

Code d'erreur : EXTERNAL_SERVICE
Code de statut : 500

Description : Un service externe requis pour cette opération a échoué.

Scénarios courants :

• Échec de l'API du fournisseur LLM
• Échec de l'intégration tierce (Google Drive, Slack, etc.)
• Délai d'attente de l'API externe

Dépannage :

1. Vérifiez l'état du service externe
2. Vérifiez les clés API/identifiants pour les services externes
3. Relancez la requête
4. Vérifiez la configuration de l'intégration
5. Contactez le support si le problème persiste

INFRASTRUCTURE

Code d'erreur : INFRASTRUCTURE
Code de statut : 500

Description : Erreur d'infrastructure (base de données, stockage, etc.).

Dépannage :

1. Relancez la requête
2. Vérifiez l'état du système
3. Si le problème persiste, contactez le support
4. Fournissez les détails de l'erreur et l'horodatage

OPEN_AI_FAILED

Code d'erreur : OPEN_AI_FAILED
Code de statut : 500

Description : L'appel API OpenAI a échoué.

Dépannage :

1. Vérifiez l'état du service OpenAI
2. Vérifiez que la clé API est valide et dispose de crédits
3. Vérifiez les limites de débit
4. Relancez avec un backoff exponentiel
5. Vérifiez la disponibilité du modèle

503 Service indisponible

Service temporairement indisponible.

EXECUTION_TIMEOUT

Code d'erreur : EXECUTION_TIMEOUT
Code de statut : 503

Description : Opération expirée.

Dépannage :

1. Relancez la requête
2. Simplifiez l'opération si possible
3. Vérifiez si le système est surchargé
4. Divisez les grandes opérations en opérations plus petites
5. Contactez le support si le délai d'attente persiste

Erreurs de logique métier

QUOTA_EXCEEDED

Code d'erreur : QUOTA_EXCEEDED
Code de statut : 400 ou 429

Description : Vous avez dépassé votre limite de quota.

Dépannage :

1. Vérifiez votre utilisation actuelle dans Mon compte > Tableau de bord
2. Examinez les limites d'abonnement
3. Mettez à niveau votre plan si nécessaire
4. Attendez la période de réinitialisation du quota
5. Contactez le service commercial pour une augmentation de quota

FEATURE_DISABLED

Code d'erreur : FEATURE_DISABLED
Code de statut : 400

Description : Cette fonctionnalité est désactivée pour votre compte.

Dépannage :

1. Vérifiez votre plan d'abonnement
2. Vérifiez la disponibilité des fonctionnalités
3. Mettez à niveau le plan si la fonctionnalité nécessite un niveau supérieur
4. Contactez le support pour l'accès aux fonctionnalités

FLOW_IN_USE

Code d'erreur : FLOW_IN_USE
Code de statut : 400

Description : Le workflow est actuellement utilisé et ne peut pas être modifié.

Dépannage :

1. Attendez que les exécutions actives se terminent
2. Annulez les exécutions de workflow actives
3. Vérifiez l'état d'exécution du workflow
4. Relancez après la fin des exécutions

EXISTING_USER

Code d'erreur : EXISTING_USER
Code de statut : 400

Description : Un utilisateur avec cet e-mail existe déjà.

Dépannage :

1. Essayez de vous connecter au lieu de vous inscrire
2. Utilisez la réinitialisation du mot de passe si vous avez oublié vos identifiants
3. Utilisez une adresse e-mail différente
4. Contactez le support si une récupération de compte est nécessaire

Erreurs spécifiques à l'intégration

INVALID_APP_CONNECTION

Code d'erreur : INVALID_APP_CONNECTION
Code de statut : 400

Description : Connexion d'application invalide ou expirée (intégration OAuth).

Dépannage :

1. Réauthentifiez l'intégration
2. Vérifiez l'expiration du jeton OAuth
3. Vérifiez les identifiants de l'intégration
4. Reconnectez l'intégration dans les paramètres

INVALID_SAML_RESPONSE

Code d'erreur : INVALID_SAML_RESPONSE
Code de statut : 400

Description : Réponse SAML invalide du fournisseur SSO.

Dépannage :

1. Vérifiez la configuration SSO
2. Vérifiez l'URL des métadonnées SAML
3. Assurez-vous que le fournisseur SSO est accessible
4. Contactez le support pour l'examen de la configuration SSO

RATE_LIMITED

Code d'erreur : RATE_LIMITED ou ratelimited
Code de statut : 429

Description : Limite de débit de l'API dépassée.

Dépannage :

1. Attendez que la fenêtre de limite de débit se réinitialise
2. Implémentez un backoff exponentiel
3. Réduisez la fréquence des requêtes
4. Vérifiez les en-têtes de limite de débit dans la réponse
5. Mettez à niveau votre plan pour des limites de débit plus élevées

Obtenir de l'aide

Si vous rencontrez une erreur qui ne figure pas ici ou si vous avez besoin d'assistance :

1. Vérifiez les détails de l'erreur : Notez le code d'erreur, le message et l'error_id
2. Vérifiez l'état du système : Visitez status.getodin.ai pour les problèmes connus
3. Consultez la documentation : Vérifiez la documentation pertinente de l'API
4. Contactez le support : Envoyez un e-mail à Support avec :
   • Code d'erreur et message
   • ID d'erreur (si disponible)
   • Étapes pour reproduire
   • Détails de la requête/réponse (assainis)
   • Horodatage de l'erreur