GloopAPI-Integrationsleitfaden
Fehlerbehandlung
Fehler und Grenzen für Wiederholungen behandeln.
Stellen Sie zuerst fest, ob die Anfrage angenommen wurde, und entscheiden Sie erst dann über eine Wiederholung. Endpunktseiten zeigen tatsächliche Statuscodes, Fehlerhüllen und repräsentative Fehler. Verschiedene Protokolle verwenden nicht unbedingt dieselbe JSON-Struktur; auch binäre Erfolgsantworten können im Fehlerfall JSON liefern.
Entscheidung anhand der Antwort
| Signal | Nächster Schritt |
|---|---|
| 400 / Feld oder Modell nicht unterstützt | Eingaben anhand des Endpunkt-schema und aktuellen Funktionskatalogs korrigieren; nicht unverändert endlos wiederholen |
| 401 / 403 | Gültigkeit der Key, Konto, IP, Modell- oder Tool-Berechtigungen und Kontingent prüfen |
| 402 / unzureichendes Kontingent | Budget erhöhen oder Umfang der neuen Anfrage verringern; vorhandene Aufgaben weiter über ihren ursprünglichen Datensatz wiederherstellen |
| 404 | Ressourcenidentität, Pfad und Schalter prüfen; daraus nicht ableiten, dass eine unbekannte Übermittlung nie ausgeführt wurde |
| 409 | Idempotenzkonflikt, noch nicht bereite Aufgabe, geänderten Kostenvoranschlag oder referenzierte Ressource unterscheiden und den konkreten Fehler behandeln |
| 410 | Ursprüngliche Ressource gelöscht oder abgelaufen; Abrechnungs- und Idempotenznachweise behalten, nicht automatisch eine neue Aufgabe erstellen |
| 429 / 5xx / Netzwerk-Timeout | Nach Begrenzungspause oder Wiederherstellung des Dienstes Annahme prüfen; sichere Wiederholung setzt einen Idempotenzvertrag voraus |
Angenommen und unbekannt
HTTP 202 bedeutet angenommen oder noch nicht abgeschlossen. Tools können auch fehlgeschlagene Aufgaben mit HTTP 200 zurückgeben; lesen Sie status. Ein angenommener Abbruch ist kein endgültiger Abbruchzustand. Eine Streamingantwort mit HTTP 200 kann Fehlerereignisse enthalten oder unerwartet abbrechen.
Behalten Sie bei Erstellungs-Timeout, unknown und billing_review den ursprünglichen Schlüssel und verwenden Sie die asynchrone Wiederherstellung. Erneutes Speichern und erneute Generierung sind unterschiedliche Vorgänge. Ist die Dateiquelle abgelaufen, kann auch ein erneuter Speicherversuch erfolglos bleiben.
Diagnoseinformationen
Protokollieren Sie Zeit, Methode, Pfad, HTTP-Status, Fehlercode, verfügbare request_id, Aufgaben-ID und geschäftlichen Anfrageschlüssel. Entfernen Sie sensible Anfrageinhalte und protokollieren Sie keine API-Schlüssel oder signierten Links. Nutzen Sie die von der API zurückgegebenen Fehlerinformationen und Nutzungsaufzeichnungen zur Diagnose.
Automatische Wiederholungen benötigen Grenzen für Anzahl und Dauer. Prüfen Sie kostenpflichtige Anfragen zuerst, wenn deren Nichtannahme nicht nachweisbar ist; erneute Einreichung darf nicht die Standardstrategie zur Wiederherstellung sein.
Stabile Tool-Fehlercodes
| Maschinencode | HTTP | Sichere Behandlung |
|---|---|---|
| invalid_input | 400 | Genaue version und input_schema prüfen und Eingaben der neuen Anfrage korrigieren |
| invalid_cursor | 400 | Cursor nicht selbst konstruieren; erste Seite aktualisieren, um einen neuen next_cursor zu erhalten |
| quote_required / budget_required | 400 | Kostenvoranschlag oder Kostenlimit für neue Aufrufe gemäß Funktionsfeldern ergänzen |
| quote_expired / quote_stale / invalid_quote | 409 | Nur für nachweislich noch nicht eingereichte neue Aufrufe nach Prüfung neu kalkulieren; nicht vorhandene und fremde Kostenvoranschläge liefern beide invalid_quote ohne Offenlegung des Eigentümers |
| budget_exceeded | 409 | Budget für neuen Aufruf unzureichend; maximum_usd prüfen und Budget ausdrücklich wählen |
| idempotency_conflict | 409 | Anfrage mit gleichem Schlüssel wurde geändert; ursprüngliche vollständige Anfrage wiederfinden, nicht automatisch mit anderem Schlüssel senden |
| tool_service_unavailable | 503 | Infrastrukturfehler oder Funktion vorübergehend nicht verfügbar; unbekannte Übermittlung weiterhin mit ursprünglicher Identität, Schlüssel und vollständiger Anfrage wiederherstellen |
Fragen Sie bei unbekanntem Erstellungsergebnis zuerst die ursprüngliche run_id ab. Ohne run_id wiederholen Sie die vollständige ursprüngliche Erstellungsanfrage mit ursprünglicher Key und Idempotency-Key einschließlich quote_id und max_cost_usd. Ändern Sie unbekannte Übermittlungen nicht aufgrund eines abgelaufenen Kostenvoranschlags oder deaktivierten Schalters. Nur ein neuer Geschäftsvorgang, der nachweislich nicht angenommen wurde, darf neu kalkuliert werden oder einen neuen Anfrageschlüssel erhalten.