Bonnes pratiques et gestion des erreurs

Suivre le traitement

Conservez le RUN_ID dès la réponse 202. Si la notification est configurée, attendez le callback et prévoyez une reprise par /status et /output en son absence. Sans notification, interrogez le statut toutes les quelques secondes, puis espacez les appels si nécessaire. Dédupliquez les résultats de ces deux parcours avec le même run_id, pour éviter une double importation. Sur completed, récupérez le résultat ; sur failed ou cancelled, arrêtez le suivi automatique. Sur paused, conservez le suivi sans resoumettre.

Reprendre un téléchargement

Téléchargez les pièces dès que le résultat est disponible. Si un lien expire, obtenez-en un nouveau via /file, ou relisez /output. Conservez le JSON, le RUN_ID, la reference_piece et le file_id pour reprendre uniquement les fichiers manquants.

Un nouveau POST crée un nouveau traitement. Il ne doit pas servir à renouveler une URL ou à reprendre un téléchargement. Avant de resoumettre après une interruption réseau, vérifiez si vous avez déjà obtenu un identifiant de suivi et évitez une double importation.

Vérifier et importer

• Conservez le token côté serveur et les liens signés confidentiels.
• Pour recevoir un webhook, utilisez une URL de notification unique, signée et temporaire, puis vérifiez sa signature et son expiration côté logiciel métier.
• Validez les chemins : les fichiers doivent rester dans le répertoire de la demande.
• Vérifiez la taille et le SHA-256 lorsqu’ils sont fournis, puis validez le JSON et les règles métier avant import.
• Distinguez la fin du traitement Raydocs de la réussite de l’import dans votre logiciel métier.
• Conservez les identifiants des fichiers, pas les URL signées comme références durables.

Erreurs HTTP

Les erreurs de transfert multipart sont rejetées avec HTTP 422 avant création du run. Corrigez la requête ; aucun RUN_ID n’a été créé et aucun callback n’est envoyé. Ne comptez pas non plus sur une notification pour une annulation manuelle. Un fichier inconnu ou inaccessible peut renvoyer 404 depuis /file. Le téléchargement d’un lien signé expiré ou invalide peut être refusé avec 401 ; demandez un nouveau lien si le fichier reste disponible.

Erreurs métier

Un traitement failed n'a pas d'output métier. Si le workflow échoue volontairement avec un code métier public, /output renvoie ce code:

{
  "status": "failed",
  "error": {
    "code": "UNSUPPORTED_ACT_TYPE",
    "message": "Type d'acte non supporté par ce workflow."
  }
}

Les erreurs contrôlées d’entrée et d’analyse exposent un code public :

• EMPTY_INPUT_FILE : au moins un fichier transmis avec succès contient réellement 0 octet ; vérifier le contenu local. Le message indique les noms concernés. Une erreur de transfert détectée est rejetée par le POST avant création du run.
• EMAIL_PARSING_INCOMPLETE : email illisible, format MSG non exploitable comme email ou perte de contenu détectée ; fournir un email lisible ou ses documents séparément.
• DOCUMENT_ANALYSIS_FAILED : document illisible ou format non analysable ; vérifier le fichier et utiliser un format pris en charge.
• ARCHIVE_PARSING_INCOMPLETE : ZIP illisible ou limites d’extraction dépassées (100 fichiers et 200 Mo décompressés) ; fournir une archive lisible ou envoyer les documents séparément. Pour une erreur technique interne, Raydocs renvoie volontairement un message générique:

{
  "status": "failed",
  "error": {
    "code": "WORKFLOW_RUN_FAILED",
    "message": "Workflow run failed."
  }
}

Livraison de la notification

Une erreur de livraison du callback ne remplace ni le JSON métier ni l’erreur initiale. Les erreurs publiques des sous-workflows remontées au parent sont notifiées par le parent ; les diagnostics techniques internes restent masqués avec WORKFLOW_RUN_FAILED. Les règles de réception et de reprise décrivent l’accusé 2xx, les tentatives et la déduplication durable.