Codes d'erreur
Cette page constitue la source de vérité unique pour la gestion des erreurs. Les codes d'erreur spécifiques aux SDK sont documentés dans la page Gestion des erreurs de chaque SDK ; cette page couvre les erreurs au niveau du contrat API.
Codes de statut HTTP
| Code | Signification | Où il s'applique |
|---|---|---|
200 OK | La requête a réussi. | Tous les contrats. |
201 Created | Ressource créée (rare ; la plupart des créations retournent 200). | Contrat API. |
400 Bad Request | Le payload est mal formé ou des champs obligatoires sont manquants. Le corps identifie les champs problématiques. | Tous les contrats. |
401 Unauthorized | Authentification manquante, expirée ou invalide. | Tous les contrats. |
403 Forbidden | L'authentification est valide, mais le tenant n'est pas activé pour la ressource demandée (ex. : appel d'une capacité absente de votre APIKEY). | Web & SDK, API. |
404 Not Found | La ressource n'existe pas ou n'appartient pas au tenant authentifié. | Tous les contrats. |
409 Conflict | La ressource existe, mais n'est pas dans l'état adéquat pour cette opération (ex. : récupération de documents d'un processus encore en cours). | Web & SDK, API. |
410 Gone | La ressource existait, mais a été supprimée conformément à la politique de rétention (endpoints de récupération de documents), ou le processus existe mais s'est terminé en état d'erreur — voir Récupérer un processus. | Endpoints de récupération de documents ; API Get Process. |
429 Too Many Requests | Vous avez atteint la limite de débit. Réessayez avec un backoff exponentiel. | Tous les contrats. |
5xx | Erreur de plateforme. Réessayez avec un backoff ; en cas de persistance, contactez le support avec le corps de la réponse et l'horodatage. | Tous les contrats. |
Erreurs d'authentification (401)
| Cause | Symptôme |
|---|---|
| Mauvaise clé privée (assertion signée avec la mauvaise clé) | 401, Authentication failed (1.2.21) |
aud ne correspond pas à l'URL de l'environnement | 401 |
Claim exp dans le passé | 401, Authentication failed |
Algorithme non pris en charge (utilisez RS256) | 401 |
| Mélange d'identifiants sandbox / production | 401, même si les identifiants semblent corrects |
En-tête APIKEY manquant (contrat API uniquement) | 401 |
x-api-key invalide (Magic Link uniquement) | 401 |
Voir Authentification > Erreurs courantes pour la liste de vérification complète.
Politique de réessai
| Statut | Doit réessayer ? | Comment |
|---|---|---|
5xx | Oui | Backoff exponentiel (1s, 2s, 4s, 8s, …). Plafonné à 5 tentatives. |
429 | Oui | Respectez l'en-tête Retry-After si présent ; sinon, backoff exponentiel. |
4xx (autre) | Non | La requête est incorrecte. Corrigez les données avant de réessayer. |
401 | Conditionnellement | Actualisez le jeton d'accès une fois. Si la nouvelle requête retourne également 401, le problème est structurel — ne réessayez pas. |
La plateforme IDCloud n'expose actuellement pas de mécanisme de clé d'idempotence sur les endpoints de création. Soyez prudent lorsque vous réessayez POST /client/v1/process ou POST /processes/v1 — une erreur réseau sur un 5xx peut avoir réellement réussi côté serveur, et un nouvel essai créerait un processus en double. En cas de doute, récupérez les processus récents via votre ID de corrélation interne avant de réessayer.
Où vivent les erreurs SDK
Les catalogues d'erreurs du Web SDK, Android SDK, iOS SDK et Flutter SDK sont documentés dans la page Gestion des erreurs dédiée à chaque SDK :
- Web SDK > Gestion des erreurs
- Android SDK > Gestion des erreurs
- iOS SDK > Gestion des erreurs
- Flutter SDK > Gestion des erreurs
Ces pages couvrent les erreurs côté appareil (permission caméra refusée, délai de capture dépassé, réseau inaccessible sur l'appareil) — distinctes des erreurs côté API documentées ici.