Erreurs
Gérer les erreurs Kadryn d’authentification, validation, policy, provider, rate limit et serveur.
Les erreurs Kadryn doivent être gérées par classe.
Ne traitez pas chaque réponse non-2xx comme retryable.
Certains échecs exigent un retry. D’autres exigent des changements de configuration, de métadonnées, de permissions ou de policy.
Classes d’erreurs
| Classe | Retry ? | Correction typique |
|---|---|---|
| Authentification | Non | Corriger ou faire tourner la clé API Kadryn. |
| Autorisation | Non | Vérifiez le rôle, le forfait et l’accès au workspace. |
| Validation | Non | Corriger le payload, les headers ou les métadonnées. |
| Blocage policy | Non | Inspecter la décision Guardrails et mettre à jour la configuration si nécessaire. |
| Clé provider | Non | Ajouter, corriger ou faire tourner la clé provider. |
| Erreur provider | Parfois | Suivre les consignes spécifiques au provider. |
| Rate limit | Oui | Backoff et préserver l’idempotence. |
| Timeout | Oui | Retry en sécurité avec l’idempotence. |
| Erreur serveur | Oui | Retry avec backoff borné. |
Erreur d’authentifications
Causes fréquentes :
- header
Authorizationmanquant; - clé API invalide;
- clé provider utilisée à la place d’une clé API Kadryn;
- clé rattachée à un autre workspace;
- clé tournée, mais service non redéployé.
Corrigez l’authentification avant de retry.
Erreur de validations
Les erreurs de validation signifient que la forme de la requête est incorrecte.
Causes fréquentes :
Content-Type: application/jsonmanquant;- JSON invalide;
- timestamp invalide;
- coût numérique envoyé comme nombre flottant plutôt que comme chaîne en cents;
- champ provider ou model non supporté;
- métadonnées requises par la policy manquantes.
Ne retryez pas des erreurs de validation inchangées.
Policy blocks
Un blocage policy signifie que Kadryn a reçu la requête, mais que la gouvernance l’a refusée.
Causes fréquentes :
- cap budgétaire atteint;
- modèle non autorisé;
- métadonnées production manquantes;
- approbation requise;
- environnement restriction;
- restriction d’entitlement liée au forfait.
Ouvrez Logs & Traces et inspectez la décision.
Rate limits
Les rate limits peuvent être appliqués par Kadryn ou par le provider amont.
Utilisez :
- exponential backoff;
- jitter;
- retries bornés;
- idempotency clés;
- queue-based retry pour workers.
Error logging
Logguez assez d’informations pour déboguer sans exposer de secrets.
Champs sûrs :
- statut code;
- erreur code;
- Kadryn request ID;
- trace ID;
- request group ID;
- projet;
- environnement;
- provider;
- model.
Champs non sûrs :
- Authorization header;
- Kadryn API clé;
- provider clé;
- raw secret métadonnées;
- sensible prompt content.
Workflow de dépannage
- Identifiez le code de statut et le code d’erreur.
- Recherchez par request ID ou trace ID dans Logs & Traces.
- Vérifiez Diagnostics pour les problèmes de configuration.
- Vérifiez la readiness de la clé provider si Gateway échoue.
- Vérifiez les décisions de policy si la requête a été bloquée.
- Retry seulement si l’erreur est transitoire.