Passer au contenu

Référence des erreurs

Chaque endpoint de l'API NSE utilise un ensemble cohérent de codes de statut HTTP. Cette référence décrit la signification de chaque code, la structure du corps de la réponse le cas échéant, et les actions à entreprendre en cas d'erreur.


Codes de statut HTTP

400 Bad Request

La requête était structurellement invalide — un champ requis était absent, une valeur était du mauvais type, une valeur d'énumération n'était pas reconnue, ou un champ a échoué à une vérification de format (p. ex. une chaîne devant être un UUID).

Le corps de la réponse est un objet ErrorsResponse contenant une ou plusieurs entrées d'erreur identifiant précisément le champ ou la règle ayant causé le rejet.

Action à entreprendre : Lire les détails de l'erreur dans le corps de la réponse. Corriger le contenu de la requête avant de réessayer. Ne pas réessayer avec la même requête sans modification — elle échouera à nouveau.

Causes courantes :

  • Un champ requis est absent (p. ex. pas de type sur une étape)
  • Une valeur d'énumération est en mauvaise casse ou mal orthographiée (p. ex. "signer" au lieu de "Signer")
  • Un champ UUID contient une valeur qui n'est pas un UUID valide
  • Un champ date-heure n'est pas au format ISO 8601

401 Unauthorized

La requête ne contenait pas de Bearer token valide, ou le token a expiré.

Action à entreprendre : Obtenir un nouveau JWT token et réessayer la requête avec l'en-tête Authorization: Bearer {token} mis à jour. Ne pas réessayer avec le même token s'il a expiré.


403 Forbidden

Le token est valide, mais l'utilisateur authentifié n'a pas l'autorisation d'effectuer cette opération. Cela signifie généralement que l'utilisateur ne dispose pas du rôle requis ou n'appartient pas à l'organisation spécifiée dans le chemin.

Action à entreprendre : Vérifier que l'organizationId dans le chemin de la requête correspond à l'organisation à laquelle appartient l'utilisateur, et que l'utilisateur dispose des autorisations nécessaires. Il ne s'agit pas d'une erreur transitoire — réessayer ne résoudra pas le problème.


404 Not Found

La ressource référencée dans le chemin n'existe pas. Cela s'applique aux enveloppes, étapes, destinataires, fichiers et artefacts.

Action à entreprendre : Vérifier que les identifiants dans le chemin de la requête sont corrects et que la ressource a bien été créée avant cet appel. Une erreur 404 sur une ressource récemment créée peut indiquer qu'un appel de création précédent a échoué silencieusement ou qu'un mauvais identifiant est utilisé.


422 Unprocessable Content

La requête était structurellement valide, mais n'a pas pu être exécutée en raison d'une violation de règle métier. L'entité existe et la requête est bien formée, mais l'opération n'est pas autorisée dans l'état actuel.

Le corps de la réponse est un objet ErrorsResponse avec des détails sur la règle violée.

Action à entreprendre : Lire les détails de l'erreur. La correction dépend de la règle spécifique — les scénarios courants incluent :

  • Tentative de modification d'une enveloppe déjà envoyée
  • Tentative d'envoi d'une enveloppe sans destinataires ni fichiers
  • Placement d'une tâche de champ pour un recipientId n'appartenant pas à l'enveloppe
  • Tentative de création d'une ressource sur une enveloppe dont le statut n'est pas draft

500 Internal Server Error

Une erreur inattendue s'est produite côté serveur. Elle n'est pas causée par le contenu de la requête.

Action à entreprendre : Réessayer la requête après un court délai. Si l'erreur persiste, cela indique un problème de plateforme. Contacter le support Namirial avec les détails de la requête et l'horodatage afin que l'incident puisse être investigué.


Le corps ErrorsResponse

Les réponses d'erreur incluent un corps d'erreur structuré. Le schéma est nommé ErrorsResponse et contient une liste d'entrées d'erreur décrivant ce qui s'est passé.

Remarque : Les noms exacts des champs du schéma ErrorsResponse ne sont pas confirmés par la spécification API actuelle. Inspecter le corps de la réponse réelle dans l'intégration pour déterminer la structure précise. Le corps sera toujours au format JSON.


Tableau de référence rapide

CodeNomAction requise
400Bad RequestCorriger le contenu de la requête
401UnauthorizedRenouveler le Bearer token
403ForbiddenVérifier l'identifiant de l'organisation et les autorisations de l'utilisateur
404Not FoundVérifier que l'identifiant de la ressource existe
422Unprocessable ContentCorriger la violation de règle métier
429Too Many RequestsImplémenter un backoff, réduire la fréquence des appels
500Internal Server ErrorRéessayer ; contacter le support si le problème persiste