Erreurs API Didit : codes de statut, formats et solutions

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 et 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	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
`502`	Un service dont dépend Didit a renvoyé une erreur	Lire `code`	Voir Réessais
`503`	Un service dont dépend Didit est temporairement indisponible	Lire `code` et réessayer	Voir Réessais

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.

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 et Clés API 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 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 : limites, en-têtes et corps de la réponse 429.
Authentification API : comment envoyer votre clé.
Tests en sandbox : reproduisez les résultats sans données réelles ni facturation.
Webhooks : livraison, réessais et ordre.

Guides

Authentification

Model Context Protocol (MCP)

SDK web

SDK natifs

SDK serveur

Intégrations

Erreurs API Didit : codes de statut, formats et solutions

Codes de statut

Corps d’erreur

Erreurs de clé API

Crédits insuffisants

Codes d’erreur

Accès et facturation

Requêtes et idempotence

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

Vérification d’entreprise (KYB)

Portefeuilles Digital ID

Rapports et dossiers

Signatures électroniques

Webhooks

Réessais et idempotence

Voir aussi

​Codes de statut

​Corps d’erreur

​Erreurs de clé API

​Crédits insuffisants

​Codes d’erreur

​Accès et facturation

​Requêtes et idempotence

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

​Vérification d’entreprise (KYB)

​Portefeuilles Digital ID

​Rapports et dossiers

​Signatures électroniques

​Webhooks

​Réessais et idempotence

​Voir aussi

Codes de statut

Corps d’erreur

Erreurs de clé API

Crédits insuffisants

Codes d’erreur

Accès et facturation

Requêtes et idempotence

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

Vérification d’entreprise (KYB)

Portefeuilles Digital ID

Rapports et dossiers

Signatures électroniques

Webhooks

Réessais et idempotence

Voir aussi