Guida all'integrazione GloopAPI
Gestione degli errori
Gestisci errori e limiti dei tentativi.
Stabilisci prima se la richiesta è stata accettata, poi decidi se riprovare. Le pagine degli endpoint elencano i codici di stato effettivi, gli involucri degli errori e gli errori rappresentativi. Protocolli diversi non condividono necessariamente la stessa struttura JSON; anche una risposta binaria di successo può diventare JSON in caso di errore.
Decisioni in base alla risposta
| Segnale | Passaggio successivo |
|---|---|
| 400 / campo o modello non supportato | Correggi gli input in base allo schema dell'endpoint e al catalogo attuale, senza ripetere ciclicamente la stessa richiesta |
| 401 / 403 | Verifica validità della Key, account, IP, autorizzazioni del modello o dello strumento e quota |
| 402 / quota insufficiente | Aumenta il budget o riduci l'ambito della nuova richiesta; per le attività esistenti continua a recuperare il record originale |
| 404 | Verifica identità della risorsa, percorso e abilitazioni; non dedurne che un invio sconosciuto non sia mai stato eseguito |
| 409 | Distingui conflitto di idempotenza, attività non pronta, preventivo cambiato o risorsa referenziata; gestisci l'errore specifico |
| 410 | La risorsa originale è stata eliminata o è scaduta; conserva prove contabili e di idempotenza, senza creare automaticamente un'altra attività |
| 429 / 5xx / timeout di rete | Dopo l'attesa per il limite di frequenza o il ripristino del servizio, verifica l'accettazione; una ripetizione sicura richiede un contratto di idempotenza |
Accettato e sconosciuto
HTTP 202 indica accettazione o completamento ancora in attesa. Gli strumenti possono restituire un'attività fallita anche con HTTP 200: leggi status. L'accettazione dell'annullamento non equivale allo stato terminale annullato. Una risposta in streaming con HTTP 200 può contenere eventi di errore o interrompersi in modo anomalo.
Per timeout di creazione, unknown e billing_review, conserva la chiave originale e usa il recupero asincrono. Riprovare il salvataggio e rigenerare sono operazioni diverse; se la fonte del file è scaduta, anche il nuovo salvataggio potrebbe non riuscire.
Informazioni diagnostiche
Registra ora, metodo, percorso, stato HTTP, codice di errore, request_id disponibile, ID attività e chiave della richiesta. Rimuovi i dati sensibili e non registrare chiavi API o URL firmati. Usa le informazioni di errore restituite dall’API e i registri di utilizzo per la diagnosi.
I tentativi automatici devono avere limiti di numero e durata. Verifica prima le richieste a pagamento di cui non puoi dimostrare la mancata accettazione; il reinvio non deve essere la strategia predefinita di recupero.
Codici di errore stabili degli strumenti
| Codice macchina | HTTP | Gestione sicura |
|---|---|---|
| invalid_input | 400 | Verifica version e input_schema esatti e correggi gli input della nuova richiesta |
| invalid_cursor | 400 | Non costruire manualmente il cursore; aggiorna la prima pagina per ottenere un nuovo next_cursor |
| quote_required / budget_required | 400 | Per nuove chiamate, aggiungi preventivo o limite di costo in base ai campi delle funzionalità |
| quote_expired / quote_stale / invalid_quote | 409 | Richiedi un nuovo preventivo soltanto dopo aver verificato che la nuova chiamata non sia stata inviata; preventivi inesistenti o di altri restituiscono entrambi invalid_quote senza rivelare la proprietà |
| budget_exceeded | 409 | Budget insufficiente per la nuova chiamata; controlla maximum_usd e scegli esplicitamente il budget |
| idempotency_conflict | 409 | La richiesta è cambiata con la stessa chiave; recupera la richiesta completa originale senza cambiarla automaticamente per riprovare |
| tool_service_unavailable | 503 | Errore infrastrutturale o funzionalità temporaneamente non disponibile; recupera gli invii sconosciuti con identità, chiave e richiesta completa originali |
Per una creazione dall'esito sconosciuto, interroga prima il run_id originale. Se manca, ripeti la richiesta completa originale con Key e Idempotency-Key originali, includendo quote_id e max_cost_usd. Non modificare un invio sconosciuto perché il preventivo è scaduto o un'abilitazione è stata disattivata. Soltanto una nuova operazione aziendale certamente non accettata può ricevere un nuovo preventivo o una nuova chiave di richiesta.