Codes d'erreur de l'API

Lorsqu'une requête vers l'API Workflows échoue, la réponse inclut un code d'erreur structuré au format WF_XXXX :

{
  "detail": "Workflow execution not found",
  "code": "WF_1100"
}

{
  "detail": "Workflow execution not found",
  "code": "WF_1100"
}

Pour les erreurs 4xx, detail contient un message spécifique décrivant le problème. Pour les erreurs 5xx, detail est toujours "An error occurred" — la cause réelle est enregistrée côté serveur.

Unknown Error · 500 Internal Server Error

Erreur générique pour les cas ne correspondant à aucun code spécifique. Si vous rencontrez cette erreur, consultez les logs serveur ou contactez l'équipe plateforme.

Invalid Request · 422 Unprocessable Entity

La requête est bien formée mais contient des données invalides. Actuellement retourné lors de la fourniture d'un ID d'événement invalide pendant une réinitialisation de workflow — la réponse inclut un champ valid_reset_events listant les alternatives valides.

{
  "detail": "Invalid event ID for reset",
  "code": "WF_1001",
  "valid_reset_events": [3, 7, 12]
}

{
  "detail": "Invalid event ID for reset",
  "code": "WF_1001",
  "valid_reset_events": [3, 7, 12]
}

Workflow Not Found · 404 Not Found

L'exécution du workflow n'existe pas. Cela signifie généralement que l'ID d'exécution est incorrect ou que le workflow a été purgé.

Résolution : Vérifiez l'ID d'exécution. Consultez le tableau de bord Workflows pour obtenir l'ID correct.

Workflow Already Started · 409 Conflict

Une exécution de workflow avec le même ID est déjà en cours. Les ID de workflow doivent être uniques au sein d'un espace de travail.

Résolution : Utilisez un ID d'exécution différent, ou attendez la fin de l'exécution existante. Si vous devez la redémarrer, terminez d'abord l'exécution en cours.

Workflow Not Running · 409 Conflict

Vous avez tenté une action (signal, query, update ou terminate) sur un workflow qui n'est plus en cours d'exécution. La réponse inclut le statut actuel du workflow.

{
  "detail": "Workflow not running",
  "code": "WF_1102",
  "status": "COMPLETED"
}

{
  "detail": "Workflow not running",
  "code": "WF_1102",
  "status": "COMPLETED"
}

Résolution : Vérifiez le statut actuel du workflow. S'il est terminé ou en échec, démarrez une nouvelle exécution.

Platform Request Failed · 500 Internal Server Error ou 504 Gateway Timeout

L'appel RPC de la plateforme sous-jacente a échoué. Cela couvre les problèmes de connexion, les timeouts et les erreurs inattendues. Un code 504 indique spécifiquement un dépassement de délai (l'opération a pris trop de temps).

Résolution : Réessayez la requête. Si le problème persiste, contactez l'équipe plateforme.

Workflow Registration Failed · 500 Internal Server Error

L'enregistrement du worker a échoué — le système n'a pas pu enregistrer les définitions de workflow. Cela indique généralement une incompatibilité entre les spécifications de workflow et les identifiants de version lors du démarrage du worker.

Résolution : Consultez les logs du worker pour détecter les erreurs d'enregistrement. Vérifiez que les définitions de workflow sont valides et que le worker peut accéder à l'API.

Execution Not Found · 500 Internal Server Error

Une exécution censée exister est introuvable. Contrairement à WF_1100 (qui est un 404 pour les recherches utilisateur), cela indique une incohérence interne — l'exécution aurait dû exister à ce stade du flux.

Résolution : Il s'agit d'une erreur interne. Si elle persiste, signalez-la à l'équipe plateforme.

Schedule Failed · 422 / 500 / 503

La création ou la gestion de la planification a échoué. Le statut HTTP varie selon la cause :

Résolution : Pour 422, vérifiez votre expression cron et la taille du payload d'entrée. Pour 503, réessayez après quelques secondes. Pour 500, consultez les logs serveur.

Schedule Not Found · 404 Not Found

L'ID de planification n'existe pas. Il a peut-être déjà été supprimé ou n'a jamais été créé.

Résolution : Listez les planifications existantes pour trouver l'ID correct.

Platform Client Creation Failed · 500 Internal Server Error

Le système n'a pas pu construire un client plateforme, généralement en raison de problèmes de configuration (adresse incorrecte, identifiants invalides).

Résolution : Vérifiez la configuration de connexion (hôte, port, paramètres TLS).

Platform Initialization Failed · 500 Internal Server Error

L'enregistrement des attributs de recherche a échoué lors de l'initialisation de la plateforme. Cela se produit au démarrage du système.

Résolution : Contactez l'équipe plateforme si cela persiste.

Payload Encoding Required · 500 Internal Server Error

L'encodage du payload est obligatoire mais les données d'entrée n'étaient pas encodées. Cela se produit dans les déploiements où l'encodage du payload est activé (typiquement les déploiements hybrides où les données doivent rester chiffrées).

Résolution : Assurez-vous que votre client utilise le codec de payload. Consultez la documentation sur l'encodage des payloads pour plus de détails.

Streaming Error · 500 Internal Server Error

Une opération de streaming a échoué — connexion, publication ou lecture depuis un stream.

Résolution : Vérifiez la connectivité streaming. Consultez Streaming pour les détails de configuration.

Trace Error · 500 Internal Server Error

Échec de la récupération ou de l'analyse des traces depuis le backend Tempo. Cela peut signifier des spans manquants, des données de trace mal formées ou des problèmes de connectivité avec le fournisseur de traces.

Résolution : Vérifiez l'état de Tempo/backend de tracing. Si des traces sont manquantes, le workflow n'a peut-être pas encore émis de spans — attendez et réessayez.

Event Store Error · 500 Internal Server Error

Erreur de cohérence de base de données dans l'event store, typiquement lorsqu'un événement attendu est introuvable après un conflit.

Résolution : Il s'agit d'une erreur interne. Réessayez l'opération. Si elle persiste, signalez-la à l'équipe plateforme.

Le SDK Python (mistralai-workflows) possède son propre ensemble de codes d'erreur pour les erreurs côté worker (définitions de workflow invalides, problèmes de configuration d'activité, etc.). Ces codes sont différents des codes d'erreur d'API ci-dessus et sont documentés dans le guide Workflow Exception.