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

# Erreurs API Didit : codes de statut, formats et solutions

> Toutes les erreurs de l'API Didit : codes HTTP 401, 403, 409, 429 et 5xx, formats de réponse, codes stables et erreurs à réessayer.

L'API Didit signale un échec au moyen d'un code de statut HTTP et, dans presque tous les cas, d'un corps JSON.
Cette page détaille la signification de chaque statut, la structure du corps, les valeurs de `code` sur lesquelles vous pouvez vous baser pour votre logique conditionnelle, et les échecs que vous pouvez réessayer en toute sécurité.
Fiez-vous d'abord au statut et à `code` lorsqu'il est présent, car le texte d'un message peut changer.

## Codes de statut

| Statut | Signification | Que faire | Réessayer ? |
| - | - | - | - |
| `400` | La requête est invalide : un champ a échoué à la validation, ou une image ou un document n'a pas pu être lu | Corriger les éléments indiqués dans le corps | Après correction |
| `401` | La clé envoyée est incorrecte, malformée, révoquée ou expirée | Vérifier `DIDIT_API_KEY`, ou créer une nouvelle clé | Après correction |
| `402` | La vérification n'a pas pu être payée et n'a donc pas été exécutée | Recharger votre solde | Après rechargement |
| `403` | Aucune clé n'a été envoyée, la clé n'a pas accès à cette ressource ou action, la requête provient d'une adresse hors liste autorisée, ou le solde ne permet pas de couvrir l'appel | Lire le corps, puis consulter [Erreurs de clé API](#erreurs-de-clé-api) et [Crédits insuffisants](#crédits-insuffisants) | Après correction |
| `404` | La ressource n'existe pas, ou une session se trouve hors des workflows ou statuts de la clé | Vérifier l'identifiant et les limites de la clé | Non |
| `409` | La requête entre en conflit avec l'état actuel, par exemple une `Idempotency-Key` réutilisée ou une étape déjà exécutée | Lire `code` et recharger l'état | Selon le `code` |
| `410` | La ressource a expiré, par exemple une session ou une invitation | En créer une nouvelle | Non |
| `415` | Le corps de la requête n'est pas du JSON | Envoyer `Content-Type: application/json` | Après correction |
| `422` | Une adresse de portefeuille correspond à plusieurs blockchains, rien n'a donc été filtré ni facturé | Renvoyer avec `blockchain` défini sur l'une des valeurs de `candidate_chains` | Après correction |
| `429` | Une limite de débit ou un quota a été atteint | Attendre la durée indiquée par `Retry-After` ; voir [Limite de débit](https://docs.didit.me/fr/integration/rate-limiting.md) | Oui, après attente |
| `500` | Une erreur inattendue est survenue du côté de Didit | Réessayer avec un backoff, et contacter le support si l'erreur persiste | Voir [Réessais](#réessais-et-idempotence) |
| `502` | Un service dont dépend Didit a renvoyé une erreur | Lire `code` | Voir [Réessais](#réessais-et-idempotence) |
| `503` | Un service dont dépend Didit est temporairement indisponible | Lire `code` et réessayer | Voir [Réessais](#réessais-et-idempotence) |

## Corps d'erreur

Les corps d'erreur n'ont pas tous la même enveloppe ; traitez-les donc avec prudence.
Leur format dépend de la famille d'endpoints :

| Format | Où vous le rencontrez | Exemple |
| - | - | - |
| `detail` | La plupart des erreurs, y compris l'authentification, les ressources introuvables et les limites de débit | `{"detail": "You do not have permission to perform this action."}` |
| `detail` et `code` | Erreurs avec un code stable | `{"detail": "This application was deleted.", "code": "application_deleted"}` |
| Erreurs de champ | Validation des entrées | `{"workflow_id": ["This field is required."]}` |
| `non_field_errors` | Validation portant sur plusieurs champs | `{"non_field_errors": ["..."]}` |
| Un tableau JSON | Certaines erreurs de validation, comme lors d'un appel simulate | `["Scenario can only be armed before the verification starts."]` |
| `error` | La plupart des API autonomes | `{"error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}` |
| `error` et `code` | Erreurs d'image sur les API autonomes | `{"error": "...", "code": "invalid_image"}` |
| `error` sous forme de code, avec `detail` | Vérification de portefeuille Digital ID | `{"error": "insufficient_credits", "detail": "..."}` |

Une erreur `500` peut ne comporter aucun corps JSON ; prévoyez donc la gestion d'un corps impossible à parser.

```javascript theme={null}
const raw = await response.text();
let body = {};
try {
  body = JSON.parse(raw);
} catch {
  // A 5xx response may not be JSON: rely on response.status.
}
const code = body.code ?? null;
const message = body.detail ?? body.error ?? (Array.isArray(body) ? body[0] : raw);
```

## Erreurs de clé API

| Ce que vous avez envoyé | Statut | `detail` |
| - | - | - |
| Aucun en-tête `x-api-key` | `403` | `You do not have permission to perform this action.` |
| Une clé incorrecte, malformée ou révoquée | `401` | `Authentication credentials were not provided or are invalid.` |
| Une clé expirée | `401` | `This API key has expired.` |
| Une clé utilisée en dehors de sa liste d'adresses | `403` | `This API key can't be used from this IP address.` |
| Une clé restreinte sans accès à cette ressource ou action | `403` | `This API key has no access to this endpoint.` |
| Une clé limitée à certains workflows ou statuts, sur un endpoint qu'elle ne peut pas utiliser | `403` | `This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint.` |
| Une clé limitée à certains workflows ou statuts, sur une session hors de ces limites | `404` | `Session not found.` |
| Une clé dont l'application vient d'être supprimée | `403` | `This application was deleted.`, avec `"code": "application_deleted"` |

Pendant quelques minutes après la suppression d'une application, l'API répond avec `application_deleted`, puis elle rejette ensuite la clé comme n'importe quelle clé erronée.
Ne réessayez pas : l'application et ses clés ont été supprimées.

Consultez [Authentification API](https://docs.didit.me/fr/getting-started/api-authentication.md) et [Clés API](https://docs.didit.me/fr/console/api-keys.md) pour comprendre le fonctionnement des clés et de leurs limites.

## Crédits insuffisants

Chaque famille d'API signale un solde insuffisant à sa manière :

| Appel | Statut | Corps |
| - | - | - |
| `POST /v3/session/` | `400` | `{"detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}` |
| La plupart des API autonomes | `403` | `{"error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}` |
| `POST /v3/bank/account-check/` | `402` | `{"detail": "...", "code": "insufficient_credits"}` |
| Vérification de portefeuille Digital ID | `403` | `{"error": "insufficient_credits", "detail": "..."}` |
| Transactions, Travel Rule et validation d'adresse | `403` | `{"detail": "...", "code": "insufficient_credits"}` |

Dans le cadre d'un contrat, la création d'une session renvoie un code `403` avec `"code": "contract_billing_suspended"` lorsque les services payants sont suspendus pour votre organisation.
Les [applications sandbox](https://docs.didit.me/fr/integration/sandbox-testing.md) ne sont jamais facturées et ignorent donc ces vérifications.

## Codes d'erreur

Ces valeurs de `code` sont stables ; vous pouvez donc créer des branches conditionnelles basées sur celles-ci.
La plupart se trouvent aux côtés de `detail` ; pour la vérification de portefeuille Digital ID, le code correspond à la valeur de `error`.

### Accès et facturation

| Code | Statut | Signification |
| - | - | - |
| `insufficient_credits` | `402`, `403` | Le solde ne permet pas de couvrir l'appel |
| `contract_billing_suspended` | `403` | Les services payants sont suspendus pour cette organisation |
| `contract_rate_missing` | `402`, `403` | Le contrat ne comporte aucun tarif pour cette vérification |
| `application_deleted` | `403` | L'application de la clé a été supprimée |
| `organization_deleted` | `403` | L'organisation de la clé a été supprimée |
| `event_monitoring_disabled` | `403` | L'ingestion d'événements n'est pas activée pour cette application |
| `networks_not_entitled` | `403` | Les réseaux de fraude ne sont pas activés pour cette organisation |

### Requêtes et idempotence

| Code | Statut | Signification |
| - | - | - |
| `invalid_image` | `400` | L'image n'a pas pu être utilisée |
| `return_url_invalid` | `400` | L'URL de retour n'est pas autorisée |
| `idempotency_key_invalid` | `400` | La clé `Idempotency-Key` dépasse 255 caractères |
| `idempotency_key_reused` | `409` | La clé a déjà été utilisée avec un corps de requête différent |
| `idempotency_key_in_progress` | `409` | La première requête avec cette clé est toujours en cours ; attendez la durée indiquée par `Retry-After` |
| `verification_in_progress` | `409` | L'utilisateur est en train d'effectuer cette vérification, elle ne peut donc pas être annulée ; attendez la durée indiquée par `Retry-After` |
| `feature_override_not_pending` | `409` | La dérogation a déjà été appliquée ou a été annulée |

### Vérifications bancaires, de téléphone et de risque

| Code | Statut | Signification |
| - | - | - |
| `invalid_account_input` | `400` | Les coordonnées du compte ne sont pas valides |
| `country_not_covered` | `404` | La vérification ne couvre pas ce pays ou ce type de compte |
| `bank_not_covered` | `404` | La vérification ne prend pas en charge cette banque |
| `bank_verification_not_available` | `404` | La vérification bancaire n'est pas disponible |
| `account_check_unavailable` | `503` | La vérification est temporairement indisponible et la requête n'a pas été facturée |
| `phone_provider_unavailable` | `502` | La vérification du téléphone est temporairement indisponible ; rien n'est facturé et aucune tentative n'est décomptée |
| `risk_lookup_unavailable` | `502` | L'évaluation du risque est temporairement indisponible et la requête n'a pas été facturée |

### Vérification d'entreprise (KYB)

| Code | Statut | Signification |
| - | - | - |
| `kyb_registry_provider_unavailable` | `502` | Le registre des sociétés est temporairement indisponible |
| `kyb_registry_country_unsupported` | `400` | La recherche dans le registre ne couvre pas ce pays |
| `kyb_registry_search_limit_reached` | `429` | L'application a atteint sa limite de 600 recherches payantes par heure |
| `kyb_session_not_writable` | `409` | La session est terminée |
| `kyb_step_mismatch` | `409` | La session se trouve à une autre étape ; `next_step` indique laquelle |
| `kyb_no_party_drafts` | `409` | Il n'y a aucun brouillon de partie à soumettre |
| `kyb_parties_already_submitted` | `409` | Les parties ont déjà été soumises |
| `kyb_party_kyc_session_not_deleted` | `409` | La vérification de la partie est toujours active, elle ne peut donc pas être régénérée |

### Portefeuilles Digital ID

| Code | Statut | Signification |
| - | - | - |
| `wallet_unavailable` | `403` | Ce portefeuille n'est pas disponible pour votre application |
| `wallet_provider_unavailable` | `502` | Le portefeuille n'a pas pu démarrer, et aucun élément n'a été créé |
| `wallet_not_configured` | `503` | Cet environnement ne peut pas joindre le portefeuille |

### Rapports et dossiers

| Code | Statut | Signification |
| - | - | - |
| `report_deletion_pending` | `409` | Le rapport est en cours de suppression ; répétez la suppression pour terminer l'effacement de ses fichiers |
| `report_storage_unavailable` | `503` | Les fichiers du rapport n'ont pas pu être effacés ; répétez la suppression |
| `wallet_address_deletion_incomplete` | `503` | Un fichier stocké n'a pas pu être supprimé, la suppression a donc été interrompue ; réessayez |
| `case_request_not_waiting` | `409` | La requête n'est plus en attente du client, il n'y a donc rien à lui rappeler |
| `case_request_reminder_too_soon` | `429` | Un rappel a été envoyé récemment ; `retry_at` indique quand vous pourrez envoyer le prochain |

### Signatures électroniques

| Code | Statut | Signification |
| - | - | - |
| `signature_not_found` | `404` | La signature n'existe pas |
| `signature_field_not_found` | `404` | Le champ de signature n'existe pas |
| `signature_not_signed` | `404`, `409` | Le document n'a pas été signé |

Lors de la création de la session, les problèmes liés aux documents ci-dessous sont renvoyés comme valeur du champ concerné avec le statut `400`, par exemple `{"sign": "signature_document_changed"}` :

| Valeur | Signification |
| - | - |
| `signature_document_changed` | Le document est différent de celui envoyé initialement |
| `signature_document_not_supported` | Le format du document n'est pas pris en charge |
| `signature_document_conversion_failed` | Le document n'a pas pu être converti |
| `field_anchor_not_found` | L'ancre de texte d'un champ est introuvable dans le document |
| `field_value_missing` | Un champ ne contient aucune valeur |

### Webhooks

| Code | Statut | Signification |
| - | - | - |
| `webhook_url_missing` | `400` | La livraison ne comporte aucune URL enregistrée, rien n'est donc envoyé |
| `invalid_webhook_payload` | `400` | Les données du webhook ne sont pas dans un format valide |
| `webhook_resend_error` | `400` | La livraison stockée n'a pas pu être signée à nouveau, ou la tentative n'a pas pu aboutir |

## Réessais et idempotence

Certains échecs peuvent être réessayés en toute sécurité et d'autres non :

* **`429` :** attendez l'en-tête `Retry-After`, puis réessayez.
* **`502` et `503` :** réessayez avec une temporisation lorsque la référence de l'endpoint indique que rien n'a été facturé, comme c'est le cas pour les vérifications de téléphone, d'e-mail, bancaires et de risque.
* **`502` sur `POST /v3/database-validation/` :** lisez d'abord chaque entrée de `validation_errors`, car ce statut seul ne signifie pas une défaillance temporaire.
* **`503` sur une suppression :** répétez la même requête jusqu'à ce qu'elle renvoie `200`.
* **Autres `4xx` :** corrigez d'abord la requête, car la même requête échouera de la même manière.

`POST /v3/aml/` et la vérification de portefeuille Digital ID acceptent un en-tête `Idempotency-Key` contenant jusqu'à 255 caractères.
Répéter une requête avec la même clé et le même corps rejoue la réponse stockée, de sorte que le traitement et la facturation n'ont lieu qu'une seule fois.
La même clé avec un corps différent répond `409`, et tant que la première requête est toujours en cours d'exécution, les endpoints de portefeuille répondent `409` avec un en-tête `Retry-After`.

`POST /v3/session/` ne possède pas de clé d'idempotence ; par conséquent, si une requête de création expire, listez vos sessions par `vendor_data` avant d'en créer une autre.

## Voir aussi

* [Limite de débit](https://docs.didit.me/fr/integration/rate-limiting.md) : limites, en-têtes et corps de la réponse `429`.
* [Authentification API](https://docs.didit.me/fr/getting-started/api-authentication.md) : comment envoyer votre clé.
* [Tests en sandbox](https://docs.didit.me/fr/integration/sandbox-testing.md) : reproduisez les résultats sans données réelles ni facturation.
* [Webhooks](https://docs.didit.me/fr/integration/webhooks.md) : livraison, réessais et ordre.


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