Codes d'erreur

L'API utilise les codes HTTP standard. Cette page décrit les formats de réponse d'erreur, ce que signifie chaque code, et quand réessayer.

Résumé des codes

Code	Signification	Réessayer ?
`200`	Succès	—
`400`	Requête incohérente (combinaison de paramètres refusée)	Non : corrigez la requête
`401`	En-tête `x-api-key` absent	Non : ajoutez la clé
`403`	Clé invalide, expirée, sans droit d'écriture, portée manquante, ou licence inactive	Non
`404`	Fiche ou route introuvable	Non
`409`	Conflit : code déjà utilisé, fiche en cours d'utilisation dans Acomba, module Acomba inactif, dossier non actif	Selon le cas (voir plus bas)
`422`	Données invalides : champ obligatoire manquant, type ou valeur hors limites	Non : corrigez la requête
`500`	Erreur inattendue, ou attente trop longue d'Acomba	Oui, une fois, après un délai
`502` / `504`	Le service ExoConnect n'a pas répondu à temps ou a été interrompu	Oui, avec un délai croissant
`503`	Acomba temporairement indisponible : pause, fenêtre d'arrêt, service en démarrage, erreur Acomba	Oui, après le délai indiqué

Formats de réponse

Trois formats coexistent. Votre code doit les reconnaître tous les trois.

1. Erreur de requête : `detail`

Les erreurs d'authentification, de droits et la plupart des refus renvoient un objet detail :

{ "detail": "Cette clé API ne permet pas l'écriture" }

detail est en général un texte, parfois un objet :

{ "detail": { "error": "Le code NOUVCLI existe déjà" } }

2. Erreur de validation (`422`) : liste d'erreurs

Quand un champ manque ou n'a pas le bon type, detail est une liste, une entrée par problème. loc donne l'emplacement du champ :

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "name"],
      "msg": "Field required",
      "input": { "number": "NOUVCLI" }
    },
    {
      "type": "int_parsing",
      "loc": ["body", "payment_term_code"],
      "msg": "Input should be a valid integer, unable to parse string as an integer",
      "input": "NET30"
    }
  ]
}

Un paramètre de requête mal typé (par exemple page=abc) donne aussi un 422 de ce format.

3. Erreur Acomba : `error` et `message`

Quand Acomba refuse ou ne trouve pas une fiche, la réponse décrit l'erreur Acomba :

{
  "error": "SDKNotFoundError",
  "message": "Client 'XYZ' non trouvé",
  "error_code": null,
  "context": {}
}

`error`	Code HTTP
`SDKNotFoundError`	`404`
`SDKValidationError`	`422`
`SDKModuleInactiveError`	`409`
`SDKReservationError`	`409`
`SDKOperationError`	`503`
autre (dont l'attente trop longue d'Acomba)	`500`

error_code porte, quand il existe, le code d'erreur d'Acomba.

4. Indisponibilité : `503` avec délai

Quand l'accès à Acomba est suspendu (pause manuelle ou fenêtre d'arrêt planifiée dans ExoConnect), la réponse indique quand réessayer :

{
  "detail": "Accès SDK temporairement indisponible.",
  "reason_code": "sdk_stop_window",
  "blocked_until": "2026-03-19T02:00:00-04:00",
  "retry_after_seconds": 1800,
  "business_api_available": false
}

reason_code vaut sdk_paused (pause manuelle) ou sdk_stop_window (fenêtre d'arrêt). Quand le service ExoConnect démarre ou redémarre, le 503 porte plutôt un champ error (child_booting, child_hung…) : réessayez après quelques secondes.

Détail par code

`401` et `403` : authentification et droits

Voir Authentification pour la liste des messages. Le cas courant : une clé en lecture seule utilisée pour un POST, PUT, PATCH ou DELETE (403).

`404` : introuvable

La fiche n'existe pas, ou l'URL est fausse. Vérifiez le code ou l'id, et souvenez-vous qu'un id peut avoir été réutilisé par Acomba après une suppression (voir Concepts clés).

`409` : conflit

Situation	Que faire
Code déjà utilisé à la création	Choisissez un autre code, ou modifiez la fiche existante
Fiche en cours d'utilisation dans Acomba (réservation)	Réessayez plus tard, quand l'utilisateur Acomba a fermé la fiche
Module Acomba inactif (ex. paie non installée)	L'opération n'est pas disponible dans ce dossier
Code présent dans plusieurs types de documents	Utilisez la route par `id`
Dossier Acomba demandé non actif	Changez le dossier actif dans ExoConnect

`422` : données invalides

Lisez la liste detail : chaque entrée nomme le champ (loc) et le problème (msg). Attention : un champ inconnu n'est pas une erreur, il est ignoré. Vérifiez donc les noms de champs dans la référence de l'endpoint.

`500` : erreur inattendue

Le plus souvent, Acomba est resté occupé trop longtemps (une autre opération longue était en cours). Réessayez une fois après quelques secondes. Si l'erreur persiste, notez l'heure et la requête et contactez le soutien.

`502`, `503`, `504` : indisponibilité temporaire

503 avec retry_after_seconds : attendez ce délai.

Autre 503, 502 ou 504 : réessayez avec un délai croissant (2 s, 5 s, 15 s, 60 s).

Les requêtes GET sont déjà réessayées jusqu'à 3 fois par ExoConnect avant de vous parvenir en erreur.

Réessayer sans risque

Méthode	Réessayer après une erreur ou un délai dépassé
`GET`	Toujours sans risque
`PATCH`, `PUT`	Sans risque si vous renvoyez les mêmes valeurs
`POST`, `DELETE`	Relisez d'abord : l'opération a peut-être réussi avant la coupure. Un `POST` rejoué peut créer un doublon (sauf les lots de feuilles de temps, qui ont une clé d'idempotence)

Python

JavaScript

Diagnostiquer

Depuis l'application ExoConnect, ou avec une clé valide :

Route	Utilité
`GET /system/health`	État du service, de la base locale, de l'indexation et d'Acomba
`GET /system/sdk/runtime`	Acomba disponible, en pause ou en fenêtre d'arrêt
`GET /system/indexing/status`	Avancement de la copie locale

Pour toute question : support@exom.ca, en indiquant l'heure, la route appelée et la réponse reçue (sans jamais transmettre votre clé API).

Résumé des codes#

Formats de réponse#

1. Erreur de requête : detail#

2. Erreur de validation (422) : liste d'erreurs#

3. Erreur Acomba : error et message#

4. Indisponibilité : 503 avec délai#

Détail par code#

401 et 403 : authentification et droits#

404 : introuvable#

409 : conflit#

422 : données invalides#

500 : erreur inattendue#

502, 503, 504 : indisponibilité temporaire#

Réessayer sans risque#

Diagnostiquer#