Erreurs et supervision

Commencez par le code HTTP, puis lisez le corps et les en-têtes de corrélation. Les messages décrivent une situation, mais votre logique de reprise doit s’appuyer sur les statuts et, pour les dépôts idempotents, sur data.status.

Principaux codes

Code	Cas courant	Réaction
`200`	Lecture, modification ou reprise d’un dépôt abouti ; état terminal de suivi	Examiner la forme attendue et le statut métier
`201`	Nouvel objet ou espace créé	Conserver l’UUID
`202`	Même dépôt en cours	Respecter `Retry-After` et suivre l’état
`401`	Authentification absente ou invalide	Vérifier le compte et son secret
`403`	Souscription ou rôle insuffisant	Vérifier l’activation et les habilitations
`404`	Ressource inaccessible ou clé d’idempotence inconnue	Vérifier le contexte et le sens propre à l’endpoint
`409`	Conflit de clé, tentative échouée, espace non vide ou intégrité invalide	Examiner l’endpoint et le corps ; ne pas réessayer aveuglément
`410`	Reprise d’un dépôt réussi dont l’objet est devenu indisponible	Vérifier le cycle de vie avant toute nouvelle opération
`413`	Représentation Base64 trop volumineuse ou rejet de transport	Employer le binaire en lecture ; contrôler les limites en dépôt
`422`	Corps ou filtre invalide, empreinte différente, signature refusée, rétention non prolongée	Corriger la cause ; gérer la clé d’idempotence selon son état
`423`	Destruction avant échéance de rétention	Ne pas contourner l’échéance
`500`	Erreur applicative, stockage, configuration ou artefact indisponible	Conserver la corrélation et solliciter le support si persistant
`502`	Réponse invalide d’un prestataire de preuve	Suivre l’état du dépôt avant de décider d’une reprise
`503`	Prestataire ou stockage temporairement indisponible	Attendre et reprendre selon l’état durable

Un même code peut recouvrir plusieurs situations. 409 sur le contrôle d’intégrité a un sens différent de 409 sur un dépôt avec une clé déjà utilisée.

Consulter la santé du service

GET /api/ccfn/v1/health nécessite une authentification, une souscription active et un rôle CCFN. Il retourne un état available ou unavailable avec des contrôles de base de données, stockage et configuration des prestataires.

curl --user "$CCFN_USER" \
  "$CCFN_BASE_URL/api/ccfn/v1/health"

200 signifie que ces contrôles locaux ont réussi. Les contrôles de prestataires vérifient leur configuration et ne réalisent pas une transaction complète de cachet, validation et horodatage. Le stockage est interrogé en lecture ; le contrôle ne prouve pas à lui seul sa capacité d’écriture. Un test de dépôt de recette complète cette supervision.

503 signale qu’au moins un contrôle n’a pas réussi. Un 401 ou 403 indique d’abord un problème d’accès à cet endpoint, pas nécessairement un arrêt du CCFN.

Reprises et délais

Le dépôt comprend plusieurs appels synchrones. Un timeout du client n’implique pas l’arrêt du traitement serveur. Après une coupure réseau ou une erreur technique, interrogez le statut avec la clé d’origine. Ne générez pas automatiquement une nouvelle clé à chaque réponse 5xx.

Informations utiles au support

Transmettez l’environnement, la méthode et le chemin sans secret, la date avec fuseau, l’UUID éventuel, le code HTTP et X-Request-ID. Écartez le mot de passe, l’en-tête Authorization et le contenu Base64 du document. Les guides Datasure indiquent [email protected] pour le support client ; utilisez le canal convenu dans votre contrat.

À lire ensuite : Idempotence, Exemples d’intégration.