Erreurs

Le format des erreurs n’est pas encore uniforme : selon l’endroit où l’erreur est produite, le corps prend l’une des formes ci-dessous. Une intégration robuste se fie d’abord au code HTTP, puis lit le message dans le champ disponible (title, message ou error).

Les messages sont destinés à des humains. Ils sont le plus souvent en français, parfois en anglais, et peuvent changer : ne bâtissez pas de logique sur leur texte. Quand un champ code ou type est présent, c’est lui qu’il faut tester.

Les formats

Erreur générale (application/problem+json)

Produite par le gestionnaire d’exceptions commun de l’API :

{
  "type": "not-found",
  "title": "Asset 3f6c… not found",
  "status": 404,
  "instance": "/api/v1/entities/…/assets/3f6c…"
}

type est un identifiant court (ce n’est pas une URL) :

type	Statut	Signification
bad-request	400	paramètre invalide refusé par le service
invalid-operation	400	opération impossible dans l’état actuel de la ressource
forbidden	403	action refusée par une règle du service
ip-not-allowed	403	adresse IP hors de la liste autorisée par l’organisation
not-found	404	ressource inconnue, ou appartenant à une autre organisation
gone	410	ressource expirée, qui ne reviendra pas (téléchargement d’un rapport expiré, dont le fichier a pu être supprimé)
internal-error	500	erreur imprévue ; le titre est alors « Une erreur interne est survenue. »

Authentification

Les opérations /api/v1/auth/… renvoient la même forme sans instance, avec le type de contenu application/json : authentication-error (401), validation-error (400), registration-error (409, compte existant), invitation-error (400 ; 409 avec un champ code, account_in_other_organization, pour une adresse dont le compte appartient à une autre organisation), password-reset-error (400, lien de réinitialisation inutilisable), not-found (404). Le refus d’une adresse IP à la connexion ou au renouvellement arrive en revanche au format général (403, ip-not-allowed).

Conflits et imports (code / message)

Les conflits métier (409) et une partie des refus des imports utilisent un code stable :

{ "code": "code_already_exists", "message": "…" }

C’est le cas notamment des référentiels personnalisés, des modèles, des études EBIOS RM, de l’envoi d’une invitation (account_in_other_organization), de l’assistant de configuration (onboarding_already_completed ; entity_has_subentities et entity_has_data quand l’étape des entités omet une filiale qui ne peut pas être supprimée), de la création d’une nouvelle version de politique (POST …/policies/{id}/new-version) quand une autre version est déjà en cours (policy_version_in_progress : brouillon, en révision ou approuvée) ou qu’une version plus récente non archivée existe (policy_newer_version_exists), de la publication d’une version de politique (POST …/policies/{id}/publish) plus ancienne que la version publiée (policy_newer_version_exists), et de la suppression d’une version de politique (DELETE …/policies/{id}) publiée ou archivée (policy_not_deletable : seule une version brouillon, en révision ou approuvée peut l’être). Un document trop volumineux (au-delà de 5 Mo sur les imports) donne 413 :

{ "code": "payload_too_large", "message": "Le document dépasse la limite de taille autorisée." }

Validation de la requête

Un corps ou un paramètre qui ne respecte pas le format attendu (champ requis manquant, longueur, plage, JSON mal formé) est refusé avant d’atteindre le service, en 400, au format standard d’ASP.NET Core :

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": { "Email": ["…"] },
  "traceId": "00-…"
}

Les contraintes vérifiées à ce stade (longueurs, minimums, maximums) figurent dans la référence de l’API.

Autres formes

Quelques opérations renvoient encore un objet { "error": "…" } (mise à jour d’un contrôle, portail fournisseur) ou { "message": "…" } (conflit 409 de l’analyse d’écart), et certaines un 400 ou 404 au format standard d’ASP.NET Core (type en URL, title en anglais, traceId).

Sans corps

Statut	Cas
401	jeton absent, expiré ou invalide, compte désactivé (en-tête WWW-Authenticate: Bearer)
403	permission manquante (voir Organisation, entités et permissions)
429	limite de débit atteinte (voir Limites de débit)

Que réessayer ?

• 429 : oui, après la fin de la fenêtre d’une minute.
• 401 : renouvelez le jeton (POST /api/v1/auth/refresh) puis réessayez une fois ; si le renouvellement échoue aussi, reconnectez-vous.
• 500 : une nouvelle tentative peut réussir si la cause était passagère ; si l’erreur se répète, signalez-la avec l’heure et le chemin appelé.
• 400, 403, 404, 409, 410, 413 : non, la requête doit être corrigée.