Passer au contenu principal
Codes d’erreur canoniques et verdicts utilisés sur la plateforme Truthlocks. Ces codes sont stables et peuvent être utilisés pour la gestion programmatique des erreurs.

Verdicts de vérification

Raisons de la vérification

Lorsque vous appelez le point de terminaison Verify, la réponse inclut un tableau reasons avec un contexte supplémentaire. Ces codes de raison sont informatifs et apparaissent à côté du verdict :

Codes d’erreur API

Général

Attestations et émetteurs

Clés API

Consommateur

Identité et DID

SSO

Politique et gouvernance

Facturation et limites

Résidence des données

Erreurs récupérables vs. erreurs terminales

Lorsque vous décidez de relancer une requête échouée, utilisez le code d’état HTTP pour déterminer si l’erreur est transitoire ou permanente.

Réessayable (transitoire)

Ces erreurs sont automatiquement relancées par les SDKs lorsque MaxRetries (ou équivalent) est configuré:

Terminal (ne pas réessayer)

Ces erreurs indiquent un problème avec la requête qui ne sera pas résolu par une nouvelle tentative:
Les trois SDK gèrent automatiquement les erreurs réessayables avec un backoff exponentiel et une gigue. Vous n’avez besoin d’une logique de nouvelle tentative manuelle que si vous avez désactivé les nouvelles tentatives automatiques ou si vous souhaitez un comportement personnalisé en plus des valeurs par défaut du SDK.

Format de réponse d’erreur

Chaque réponse d’erreur renvoie un objet JSON avec deux champs :
  • code — un code d’erreur stable et lisible par machine des tableaux ci-dessus. Utilisez-le pour la gestion programmatique des erreurs.
  • message — une description lisible par l’homme de ce qui n’a pas fonctionné. Les messages peuvent changer entre les versions ; ne les utilisez pas de manière programmatique.
Les messages d’erreur qui exposeraient des détails d’infrastructure (tels que des chaînes de connexion de base de données ou des noms d’hôtes internes) sont automatiquement remplacés par un message générique avant d’être renvoyés au client. Les détails originaux ne sont enregistrés que côté serveur.

Erreurs de passerelle (RFC 7807)

Lorsqu’une requête atteint la passerelle API mais ne correspond à aucune route valide, la passerelle renvoie une réponse d’erreur structurée suivant la spécification RFC 7807 Problem Details. Cela s’applique aux erreurs 404 Not Found et 405 Method Not Allowed au niveau de la passerelle.

Format de réponse

Les erreurs de passerelle utilisent application/problem+json comme type de contenu et incluent quatre champs :

Lorsque vous voyez ces erreurs

  • 404 Not Found — Le chemin de la requête ne correspond à aucune route API. Vérifiez l’URL, y compris le préfixe de version /v1/ et le nom de la ressource.
  • 405 Method Not Allowed — Le chemin de la requête existe, mais la méthode HTTP que vous avez utilisée (par exemple, DELETE sur un point de terminaison en lecture seule) n’est pas prise en charge. Vérifiez la référence de l’API pour la méthode correcte.

Gestion des erreurs de passerelle dans le code

Si vous analysez les réponses d’erreur par programme, vérifiez l’en-tête Content-Type pour distinguer les erreurs de passerelle des erreurs d’application :
  • application/problem+json — Erreur au niveau de la passerelle (RFC 7807). Utilisez les champs status et title.
  • application/json — Erreur au niveau de l’application. Utilisez les champs code et message.
Les SDK Truthlocks gèrent automatiquement les deux formats d’erreur. Vous n’avez besoin de les distinguer que si vous appelez l’API directement.

Énumérations canoniques

Algorithme

* Ed25519 * ES256 * ES384 * ES512 * RS256 * RS384 * RS512 * PS256 * PS384 * PS512

Statut de l'émetteur

  • pending * trusted * suspended * revoked

Niveau de confiance

  • self_issued * verified_org * regulated_issuer

Statut de la clé

  • ACTIVE * DISABLED * EXPIRED * COMPROMISED

Statut de l'attestation

* ACTIVE * REVOKED * SUPERSEDED

Niveau de risque

  • unknown * low * medium * high * critical