> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Référence des codes d'erreur

> 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.

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

| Verdict | Sortie CLI | Description |
| - | - | - |
| VALID | 0 | Attestation vérifiée avec succès |
| ALTERED | 10 | Le hachage de la charge utile ne correspond pas |
| REVOKED | 11 | L'attestation a été révoquée |
| KEY\_COMPROMISED | 12 | Clé de signature marquée comme compromise |
| KEY\_EXPIRED | 13 | La clé de signature a expiré |
| LOG\_PROOF\_FAILED | 14 | La vérification de la preuve du journal de transparence a échoué |
| SIGNATURE\_INVALID | 15 | La vérification de la signature cryptographique a échoué |

### Raisons de la vérification

Lorsque vous appelez le [point de terminaison Verify](https://docs.truthlocks.com/fr/api-reference/verify.md), la réponse inclut un tableau `reasons` avec un contexte supplémentaire. Ces codes de raison sont informatifs et apparaissent à côté du verdict :

| Raison | Verdict | Description |
| :- | :- | :- |
| `document_hash_mismatch` | `ALTERED` | Le `document_hash_hex` que vous avez fourni ne correspond pas au hachage stocké au moment de la frappe |
| `document_hash_not_stored` | (tout) | L'attestation a été frappée sans hachage de document, donc la vérification du hachage de document a été ignorée |

## Codes d'erreur API

### Général

| Code | HTTP | Description |
| :- | :- | :- |
| `INVALID_INPUT` | 400 | Échec de la validation de la requête |
| `INVALID_REQUEST` | 400 | Le corps de la requête ou les paramètres sont mal formés |
| `INVALID_ID` | 400 | L'identifiant n'est pas un UUID valide |
| `NOT_FOUND` | 404 | Ressource introuvable |
| `UNAUTHORIZED` | 401 | Authentification requise |
| `FORBIDDEN` | 403 | Permission refusée |
| `CONFLICT` | 409 | Conflit d'état des ressources |
| `INTERNAL_ERROR` | 500 | Une erreur de serveur inattendue s'est produite |
| `DB_ERROR` | 500 | Une opération de base de données a échoué |

### Attestations et émetteurs

| Code | HTTP | Description |
| :- | :- | :- |
| `ISSUER_NOT_TRUSTED` | 403 | L'émetteur doit être en statut `trusted` pour émettre des attestations |
| `KEY_INACTIVE` | 400 | La clé de signature n'est pas active |

### Clés API

| Code | HTTP | Description |
| :- | :- | :- |
| `NAME_REQUIRED` | 400 | Un nom de clé est requis |
| `KEY_ID_REQUIRED` | 400 | Le paramètre d'ID de clé est manquant |
| `KEY_NOT_FOUND` | 404 | Clé API introuvable |
| `KEY_LIMIT` | 409 | Nombre maximal de clés API actives atteint (5 par consommateur) |

### Consommateur

| Code | HTTP | Description |
| :- | :- | :- |
| `CONSUMER_REQUIRED` | 400 | Une référence d'e-mail de consommateur est requise |

### Identité et DID

| Code | HTTP | Description |
| :- | :- | :- |
| `MISSING_DID` | 400 | Le paramètre DID est requis |
| `DID_NOT_FOUND` | 404 | DID introuvable ou l'émetteur associé a été révoqué |
| `MISSING_ID` | 400 | Le paramètre d'ID d'émetteur est requis |
| `EMAIL_NOT_VERIFIED` | 403 | L'adresse e-mail n'a pas été vérifiée |

### SSO

| Code | HTTP | Description |
| :- | :- | :- |
| `DISCOVERY_FAILED` | 400 | La configuration de découverte OIDC n'a pas pu être chargée |
| `METADATA_FETCH_FAILED` | 400 | Les métadonnées SAML IdP n'ont pas pu être récupérées |
| `CRYPTO_ERROR` | 500 | Une opération de chiffrement a échoué |
| `TEST_FAILED` | 400 | Le test de connexion SSO n'a pas abouti |
| `AUTH_FAILED` | 401 | L'authentification SSO a échoué |
| `INVALID_STATE` | 401 | Le paramètre d'état OAuth ou SAML est invalide |
| `EXPIRED_SESSION` | 401 | La session de connexion SSO a expiré |
| `REPLAY_DETECTED` | 401 | Le jeton d'état OAuth ou SAML a déjà été utilisé |
| `CONFIG_ERROR` | 500 | La configuration SSO est manquante ou invalide |

### Politique et gouvernance

| Code | HTTP | Description |
| :- | :- | :- |
| `POLICY_VIOLATION` | 403 | La requête viole une politique active |

### Facturation et limites

| Code | HTTP | Description |
| :- | :- | :- |
| `BILLING_LIMIT` | 402 | Quota de facturation épuisé pour le cycle actuel |
| `LIMIT_REACHED` | 429 | Limite de protection mensuelle atteinte |
| `SEAT_LIMIT` | 402 | Limite de sièges d'équipe atteinte — mettez à niveau votre plan ou supprimez un membre existant |

### Résidence des données

| Code | HTTP | Description |
| :- | :- | :- |
| `REGION_MISMATCH` | 409 | Le locataire est épinglé à une région différente de celle qui traite la requête |

## 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](https://docs.truthlocks.com/fr/sdk/go.md) lorsque `MaxRetries` (ou équivalent) est configuré:

| Statut HTTP | Code | Quand réessayer |
| :- | :- | :- |
| `408` | Délai d'attente de la requête | Immédiatement — le serveur n'a pas reçu la requête à temps |
| `429` | `RATE_LIMITED` | Après la durée spécifiée dans l'en-tête `Retry-After` |
| `500` | `INTERNAL_ERROR` | Avec un délai exponentiel — problème de serveur transitoire |
| `502` | Mauvaise passerelle | Avec un délai exponentiel — service en amont indisponible |
| `503` | Service indisponible | Avec un backoff exponentiel — service temporairement surchargé |
| `504` | Délai d'attente de la passerelle | Avec un délai exponentiel — le service en amont a expiré |

### 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:

| Statut HTTP | Exemples de codes | Action |
| :- | :- | :- |
| `400` | `INVALID_INPUT`, `INVALID_REQUEST` | Corrigez la charge utile de la requête |
| `401` | `UNAUTHORIZED` | Vérifiez votre clé API ou votre jeton d'authentification |
| `403` | `FORBIDDEN`, `ISSUER_NOT_TRUSTED`, `POLICY_VIOLATION` | Vérifier les permissions ou le statut de l'émetteur |
| `404` | `NOT_FOUND` | Vérifiez que l'ID de ressource existe |
| `409` | `CONFLICT` | Résolvez le conflit d'état avant de réessayer |

> [!TIP]
>
> 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 :

```json theme={null}
{
  "code": "ISSUER_NOT_TRUSTED",
  "message": "Issuer must be in trusted status to mint attestations"
}
```

* **`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.

> [!NOTE]
>
> 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](https://www.rfc-editor.org/rfc/rfc7807). 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 :

```json theme={null}
{
  "type": "https://docs.truthlocks.com/ops/errors",
  "title": "Not Found",
  "status": 404,
  "detail": "The requested path does not match any API route."
}
```

| Champ | Description |
| :- | :- |
| `type` | Une référence URI qui identifie le type d'erreur. Pointe vers cette page de documentation. |
| `title` | Un bref résumé de l'erreur. Soit `Not Found` ou `Method Not Allowed`. |
| `status` | Le code de statut HTTP — `404` ou `405`. |
| `detail` | Une explication lisible par l'homme de l'erreur spécifique. |

### 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](https://docs.truthlocks.com/fr/api-reference/attestations/mint.md) 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`.

```javascript theme={null}
const res = await fetch("https://api.truthlocks.com/v1/nonexistent");
const contentType = res.headers.get("content-type");

if (contentType?.includes("application/problem+json")) {
  // Gateway error — RFC 7807 format
  const problem = await res.json();
  console.error(`${problem.status} ${problem.title}: ${problem.detail}`);
} else {
  // Application error — standard format
  const error = await res.json();
  console.error(`${error.code}: ${error.message}`);
}
```

> [!TIP]
>
> Les [SDK Truthlocks](https://docs.truthlocks.com/fr/sdk/js.md) 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

> [card] Algorithme
>
> \* `Ed25519` \* `ES256` \* `ES384` \* `ES512` \* `RS256` \* `RS384` \* `RS512` \* `PS256` \* `PS384` \* `PS512`

> [card] Statut de l'émetteur
>
> * `pending` \* `trusted` \* `suspended` \* `revoked`

> [card] Niveau de confiance
>
> * `self_issued` \* `verified_org` \* `regulated_issuer`

> [card] Statut de la clé
>
> * `ACTIVE` \* `DISABLED` \* `EXPIRED` \* `COMPROMISED`

> [card] Statut de l'attestation
>
> \* `ACTIVE` \* `REVOKED` \* `SUPERSEDED`

> [card] Niveau de risque
>
> * `unknown` \* `low` \* `medium` \* `high` \* `critical`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.