Guide d'intégration GloopAPI
Gestion des erreurs
Gérer les erreurs et les limites de répétition.
Déterminez d'abord si la requête a été acceptée, puis décidez s'il faut la répéter. Les pages des points de terminaison présentent les codes d'état réels, les enveloppes d'erreur et des erreurs représentatives ; les protocoles ne partagent pas nécessairement la même structure JSON, et une réponse binaire en cas de réussite peut devenir du JSON en cas d'échec.
Décisions selon la réponse
| Signal | Étape suivante |
|---|---|
| 400 / champ ou modèle non pris en charge | Corriger les entrées selon le schema du point de terminaison et le catalogue actuel ; ne pas répéter indéfiniment à l'identique |
| 401 / 403 | Vérifier la validité de la Key, le compte, l'IP, les autorisations de modèle ou d'outil et le quota |
| 402 / quota insuffisant | Augmenter le budget ou réduire la portée de la nouvelle requête ; pour une tâche existante, poursuivre la récupération de l'enregistrement initial |
| 404 | Vérifier l'identité de la ressource, le chemin et les interrupteurs ; ne pas en déduire qu'une soumission inconnue n'a jamais été exécutée |
| 409 | Distinguer conflit d'idempotence, tâche non prête, modification du devis ou ressource référencée ; traiter l'erreur précise |
| 410 | La ressource initiale a été supprimée ou a expiré ; conserver les preuves comptables et d'idempotence, sans créer automatiquement une autre tâche |
| 429 / 5xx / délai réseau dépassé | Après temporisation liée au débit ou rétablissement du service, vérifier l'acceptation ; seule une garantie d'idempotence permet une répétition sûre |
Accepté et inconnu
HTTP 202 signifie accepté ou toujours en attente de fin ; un outil peut aussi renvoyer une tâche échouée avec HTTP 200 : lisez status. L'acceptation d'une annulation n'est pas son état terminal. Une réponse en flux HTTP 200 peut aussi contenir des événements d'erreur ou s'interrompre anormalement.
En cas de délai de création dépassé, unknown ou billing_review, conservez la clé d'origine et utilisez la récupération asynchrone. Réessayer une sauvegarde et régénérer sont des opérations différentes ; si la source du fichier a expiré, une nouvelle tentative de sauvegarde peut rester impossible.
Informations de diagnostic
Enregistrez l’heure, la méthode, le chemin, l’état HTTP, le code d’erreur, le request_id disponible, l’ID de tâche et la clé de requête métier. Expurgez les données sensibles et ne journalisez ni Key ni liens signés. Utilisez les erreurs renvoyées par l’API et les relevés d’utilisation pour le diagnostic.
Les répétitions automatiques doivent avoir des limites de nombre et de durée. Vérifiez d'abord tout appel facturable dont la non-acceptation n'est pas prouvée ; la resoumission ne doit pas être la stratégie de récupération par défaut.
Codes d'erreur stables des outils
| Code machine | HTTP | Traitement sûr |
|---|---|---|
| invalid_input | 400 | Vérifier les valeurs exactes de version et input_schema ; corriger les entrées de la nouvelle requête |
| invalid_cursor | 400 | Ne pas construire de curseur soi-même ; actualiser la première page pour obtenir un nouveau next_cursor |
| quote_required / budget_required | 400 | Pour un nouvel appel, fournir le devis ou le plafond de coût selon les champs de capacité |
| quote_expired / quote_stale / invalid_quote | 409 | Redemander un devis uniquement après vérification d'un nouvel appel confirmé non soumis ; les devis inexistants et ceux d'autrui renvoient tous invalid_quote sans divulgation de propriété |
| budget_exceeded | 409 | Budget insuffisant pour le nouvel appel ; vérifier maximum_usd puis choisir explicitement le budget |
| idempotency_conflict | 409 | La requête a changé avec la même clé ; retrouver la requête complète initiale, sans changer automatiquement de clé pour réessayer |
| tool_service_unavailable | 503 | Défaillance d'infrastructure ou capacité temporairement indisponible ; récupérer toute soumission inconnue avec l'identité, la clé et la requête complète d'origine |
Pour une création au résultat inconnu, consultez d'abord le run_id initial ; en son absence, répétez la requête complète de création avec la Key et l'Idempotency-Key d'origine, y compris quote_id et max_cost_usd. Ne modifiez pas une soumission inconnue parce que le devis a expiré ou qu'un interrupteur est désactivé. Seule une nouvelle opération métier confirmée non acceptée peut recevoir un nouveau devis ou une nouvelle clé de requête.