Codes d'erreur
2xx confirment le succès, les codes 4xx signalent une erreur côté client et les codes 5xx indiquent un problème côté serveur.Résumé des codes
| Code | Statut | Description |
|---|---|---|
| 200 | OK | La requête a été traitée avec succès. |
| 400 | Bad Request | Paramètres manquants ou format incorrect. |
| 401 | Unauthorized | En-tête x-api-key manquant ou invalide. |
| 404 | Not Found | La ressource demandée n'existe pas. |
| 409 | Conflict | L'opération entre en conflit avec l'état actuel de la ressource. |
| 422 | Unprocessable Entity | Les données envoyées ne respectent pas les contraintes métier. |
| 500 | Internal Server Error | Erreur interne du serveur. |
| 503 | Service Unavailable | Le service Acomba ou le SDK n'est pas disponible. |
Format de réponse d'erreur
detail qui décrit le problème :{
"detail": "Clé API manquante ou invalide — vérifiez le header x-api-key"
}422), l'API retourne un format plus détaillé avec la liste des champs en erreur :{
"detail": [
{
"loc": ["body", "code"],
"msg": "field required",
"type": "value_error.missing"
}
]
}Détail par code
200 — OK
Lecture (GET)
{
"items": [...],
"total": 412,
"limit": 50,
"offset": 0,
"truncated": true
}Mutation (POST / PATCH / DELETE)
{
"success": true,
"id": 416
}400 — Bad Request
| Situation | Exemple |
|---|---|
| Paramètre de query invalide | ?limit=abc au lieu d'un entier |
| Format de date incorrect | since=2026-13-01 (mois invalide) |
| Entité non supportée | ?entity=unknown dans /api/helpers/updates |
| Corps JSON mal formé | Accolades manquantes, virgule en trop |
{
"detail": "Requête invalide — paramètres manquants ou format incorrect."
}YYYY-MM-DDTHH:mm:ss) avant l'envoi. C'est la cause la plus fréquente de 400 sur les routes de synchronisation.401 — Unauthorized
x-api-key est absent ou contient une clé invalide. Aucune requête ne peut aboutir sans une clé valide.{
"detail": "Clé API manquante ou invalide — vérifiez le header x-api-key"
}| Situation | Solution |
|---|---|
| Header absent | Ajoutez x-api-key: VOTRE_CLE_API à chaque requête |
| Clé expirée ou révoquée | Générez une nouvelle clé dans l'application ExoConnect |
| Faute de frappe dans le header | Utilisez exactement x-api-key (sensible à la casse) |
| Espace ou retour de ligne | Vérifiez qu'aucun caractère invisible ne s'est glissé dans la valeur |
EXOCONNECT_API_KEY) plutôt qu'en dur dans votre code. Consultez la page Authentification pour les bonnes pratiques.404 — Not Found
{
"detail": "Ressource introuvable — le code ou l'ID spécifié n'existe pas."
}| Situation | Solution |
|---|---|
| Code métier incorrect | Vérifiez la casse exacte du code (ex : JACHETE, pas jachete) |
| ID supprimé | La fiche a été supprimée dans Acomba |
| Mauvais endpoint | Vérifiez le chemin de la route (ex : /api/customers et non /api/customer) |
/by-id/{id}) pour éviter les erreurs de casse. L'ID est immuable et ne change jamais.409 — Conflict
{
"detail": "Conflit métier — l'opération entre en conflit avec l'état actuel."
}| Situation | Solution |
|---|---|
| Code déjà utilisé | Choisissez un code unique pour la nouvelle ressource |
| Suppression d'une entité référencée | Retirez d'abord les références (factures, paiements) avant de supprimer |
| Indexation ou synchronisation déjà en cours | Attendez la fin de l'opération avant d'en lancer une nouvelle |
422 — Unprocessable Entity
{
"detail": "Erreur de validation — les données envoyées ne respectent pas les contraintes métier."
}| Situation | Solution |
|---|---|
| Champ obligatoire manquant | Consultez la documentation de l'endpoint pour les champs requis |
| Valeur hors limites | Vérifiez les longueurs max et plages acceptées (ex : code max 12 caractères) |
| Référence invalide | Le payment_term_code ou territory_code n'existe pas dans Acomba |
| Type de données incorrect | Un champ numérique reçoit une chaîne de caractères |
422 de FastAPI incluent le chemin exact du champ en erreur dans detail[].loc. Utilisez cette information pour identifier précisément quel champ corriger.500 — Internal Server Error
{
"detail": "Erreur interne — contactez le support si le problème persiste."
}| Action | Détail |
|---|---|
| Réessayer la requête | Certaines erreurs COM sont transitoires (lock temporaire) |
| Vérifier qu'Acomba est ouvert | Le SDK nécessite qu'Acomba soit lancé sur le poste |
| Consulter les logs | GET /system/logs peut révéler la cause exacte |
| Contacter le support | Si l'erreur persiste : support@exom.ca |
503 — Service Unavailable
{
"detail": "Service SDK indisponible — le runtime n'est pas initialisé."
}| Situation | Solution |
|---|---|
| Acomba n'est pas lancé | Démarrez Acomba sur le poste où l'API est installée |
| SDK en pause | Reprenez le SDK via POST /system/sdk/resume |
| Fenêtre d'arrêt active | Le SDK est dans une fenêtre d'arrêt planifiée, il reprendra automatiquement |
| Base d'indexation non initialisée | Vérifiez le statut avec GET /system/indexing/status |
GET /system/health avant de diagnostiquer une erreur 503. Cette route retourne le statut de chaque composant (SDK, base de données, relais).Bonnes pratiques de gestion des erreurs
Vérifiez le code HTTP en premier
Utilisez le code de statut HTTP pour déterminer la catégorie d'erreur avant de lire le corps de la réponse. Les codes
4xx sont des erreurs client (corrigez votre requête), les 5xx sont des erreurs serveur (réessayez ou contactez le support).Implémentez une logique de retry pour les erreurs transitoires
Les erreurs
500 et 503 peuvent être temporaires (lock COM, redémarrage SDK). Implémentez un retry avec backoff exponentiel pour ces codes, avec un maximum de 3 tentatives.Loguez le corps complet de la réponse
Le champ
detail contient souvent des informations précieuses pour le diagnostic. Loguez-le systématiquement pour faciliter le débogage.Surveillez la santé du service
Intégrez un appel périodique à
GET /system/health dans votre monitoring. Cela vous permet de détecter les interruptions avant qu'elles n'affectent vos opérations.Exemple de gestion des erreurs
Python
JavaScript
PHP
Modified at 2026-03-20 02:48:39