Gestione degli errori, limitazione della frequenza e gestione delle quote

Quando esegui query sull'API Developer Knowledge o sul server MCP Developer Knowledge nelle applicazioni di produzione e negli agenti AI, è necessario gestire gli errori e le quote per ottenere prestazioni elevate.

In questa guida imparerai a:

  • Implementa il backoff esponenziale troncato con jitter per le risposte HTTP 429.
  • Gestisci i codici di errore gRPC canonici (INVALID_ARGUMENT, PERMISSION_DENIED, RESOURCE_EXHAUSTED).
  • Gestisci i timeout di connessione MCP e la logica di ripetizione.
  • Applica le best practice per la gestione delle quote e la memorizzazione nella cache.

Limitazione della frequenza HTTP 429 e backoff esponenziale

Quando le frequenze delle richieste superano la quota API predefinita, il servizio restituisce un errore HTTP 429 Too Many Requests. Le applicazioni devono implementare la logica di nuovi tentativi utilizzando il backoff esponenziale troncato con jitter per evitare di sovraccaricare il servizio.

Backoff esponenziale troncato

Calcola i ritardi dei tentativi utilizzando la seguente formula:

retry_delay = min(max_delay, initial_delay * (2 ^ attempt) + jitter)

Utilizza i seguenti parametri per calcolare i ritardi dei tentativi:

  • initial_delay: ritardo iniziale del nuovo tentativo (ad esempio, 1 secondo).
  • max_delay: limite massimo di backoff (ad esempio, 32 secondi).
  • attempt: numero attuale di tentativi (0, 1, 2, …).
  • jitter: valore casuale compreso tra 0 e 1 secondo per evitare picchi di sincronizzazione dei thread (problema della mandria fragorosa).

Gestione degli errori gRPC

Le applicazioni che accedono al servizio tramite gRPC devono ispezionare i valori canonici di grpc.StatusCode.

Codici di stato gRPC standard

La tabella seguente elenca i codici di stato gRPC canonici restituiti dal servizio e la gestione client consigliata:

Codice di stato gRPC Stato HTTP Causa principale Azione consigliata
INVALID_ARGUMENT 400 Bad Request Stringa di query non valida, formato del parametro non valido o maschera di campo non valida. Non riprovare. Correggi i parametri della richiesta prima di ripetere l'operazione.
UNAUTHENTICATED 401 Unauthorized Chiave API o token OAuth Bearer mancante, scaduto o non valido. Non riprovare. Aggiorna le credenziali o genera una chiave API valida.
PERMISSION_DENIED 403 Forbidden La chiave API non dispone dell'autorizzazione o l'API Developer Knowledge è disabilitata nel progetto. Non riprovare. Verifica l'abilitazione dell'API nella console Google Cloud.
NOT_FOUND 404 Not Found Il percorso del documento parent specificato non esiste. BatchGetDocuments non va a buon fine in modo atomico se non viene trovato alcun documento richiesto. Non riprovare. Verifica il nome della risorsa del documento.
RESOURCE_EXHAUSTED 429 Too Many Requests Limite di frequenza o limite di quota del progetto superato. Riprova utilizzando il backoff esponenziale con jitter.
UNAVAILABLE 503 Service Unavailable Disconnessione temporanea della rete o riavvio del server. Riprova con backoff esponenziale.
DEADLINE_EXCEEDED 504 Gateway Timeout La richiesta ha superato la scadenza RPC configurata prima del completamento. Riprova con un timeout RPC client aumentato.

Timeout della connessione MCP e gestione degli errori

Il server MCP per Developer Knowledge è un servizio remoto ospitato all'indirizzo https://developerknowledge.googleapis.com/mcp a cui si accede tramite HTTPS (utilizzando HTTP POST o Server-Sent Events). Gli host e gli agenti AI devono gestire i timeout di connessione e gli errori degli strumenti in modo appropriato.

Timeout di esecuzione dello strumento

Quando un agente richiama search_documents, get_documents o answer_query, le chiamate di strumenti potrebbero superare le finestre di timeout (ad esempio, 30 secondi) se le connessioni di rete sono lente.

Per gestire i timeout di esecuzione dello strumento:

  • Configura i timeout del client: imposta i timeout di esecuzione degli strumenti su 30-60 secondi nella configurazione del client host MCP.
  • Gestisci interruzioni di rete: riprova le richieste HTTP non riuscite con backoff esponenziale in caso di interruzioni di rete temporanee o risposte HTTP 503.
  • Esamina i messaggi di errore: analizza i messaggi di errore JSON-RPC standard o i codici di stato di errore HTTP per distinguere gli argomenti non validi dall'esaurimento della quota.

Best practice per la gestione delle quote

Segui queste best practice per mantenere un utilizzo ottimale delle API ed evitare limiti di frequenza imprevisti:

  1. Memorizza nella cache i contenuti dei documenti recuperati: memorizza i documenti Markdown recuperati localmente o in una cache (ad esempio Redis) quando crei applicazioni che accedono spesso alle stesse pagine.
  2. Utilizza il recupero batch: utilizza documents.batchGet anziché eseguire più richieste documents.get sequenziali.
  3. Ottimizza i campi di query: richiedi solo i campi di risposta necessari utilizzando maschere di campo selettive (fields=results(parent,content)).
  4. Monitora il consumo della quota: monitora le frequenze delle richieste API nella dashboard API della console Google Cloud.

Contenuti correlati