Fehlerbehandlung, Ratenbegrenzung und Quotenverwaltung

Wenn Sie in Produktionsanwendungen und KI-Agents den Developer Knowledge API- oder Developer Knowledge MCP-Server abfragen, müssen Fehlerbehandlung und Kontingentverwaltung vorhanden sein, um eine hohe Leistung zu erzielen.

In diesem Leitfaden erfahren Sie, wie Sie:

  • Implementieren Sie einen abgeschnittenen exponentiellen Backoff mit Jitter für HTTP-Antworten 429.
  • Kanonische gRPC-Fehlercodes verarbeiten (INVALID_ARGUMENT, PERMISSION_DENIED, RESOURCE_EXHAUSTED).
  • Zeitüberschreitungen bei MCP-Verbindungen und Wiederholungslogik verwalten.
  • Best Practices für die Kontingentverwaltung und das Caching anwenden

HTTP 429-Ratenbegrenzung und exponentieller Backoff

Wenn die Anfrageraten das Standard-API-Kontingent überschreiten, gibt der Dienst einen HTTP 429 Too Many Requests-Fehler zurück. Anwendungen müssen eine Wiederholungslogik mit abgeschnittenem exponentiellem Backoff mit Jitter implementieren, um eine Überlastung des Dienstes zu vermeiden.

Abgeschnittener exponentieller Backoff

Verwenden Sie die folgende Formel, um die Verzögerungen für Wiederholungsversuche zu berechnen:

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

Verwenden Sie die folgenden Parameter, um die Verzögerungen bei Wiederholungsversuchen zu berechnen:

  • initial_delay: Die anfängliche Verzögerung für Wiederholungsversuche (z. B. 1, 0 Sekunde).
  • max_delay: Maximale Backoff-Obergrenze (z. B. 32, 0 Sekunden).
  • attempt: Aktuelle Anzahl der Wiederholungsversuche (0, 1, 2 ...).
  • jitter: Zufallswert zwischen 0 und 1,0 Sekunden, um Spitzen bei der Threadsynchronisierung zu vermeiden (Thundering Herd-Problem).

gRPC-Fehlerbehandlung

Anwendungen, die über gRPC auf den Dienst zugreifen, müssen kanonische grpc.StatusCode-Werte prüfen.

Standard-gRPC-Statuscodes

In der folgenden Tabelle sind die kanonischen gRPC-Statuscodes aufgeführt, die vom Dienst zurückgegeben werden, sowie die empfohlene Clientbehandlung:

gRPC-Statuscode HTTP-Status Ursache Empfohlene Maßnahmen
INVALID_ARGUMENT 400 Bad Request Fehlerhafter Abfragestring, ungültiges Parameterformat oder ungültige Feldmaske. Nicht wiederholen Korrigieren Sie die Anfrageparameter, bevor Sie die Anfrage wiederholen.
UNAUTHENTICATED 401 Unauthorized Fehlender, abgelaufener oder fehlerhafter API-Schlüssel oder OAuth-Bearer-Token. Nicht wiederholen Aktualisieren Sie die Anmeldedaten oder generieren Sie einen gültigen API-Schlüssel.
PERMISSION_DENIED 403 Forbidden Dem API-Schlüssel fehlt die Berechtigung oder die Developer Knowledge API ist im Projekt deaktiviert. Nicht wiederholen Prüfen Sie, ob die API in der Google Cloud Console aktiviert ist.
NOT_FOUND 404 Not Found Der angegebene Dokumentpfad parent ist nicht vorhanden. BatchGetDocuments schlägt atomar fehl, wenn ein angefordertes Dokument nicht gefunden wird. Nicht wiederholen Name der Dokumentressource prüfen.
RESOURCE_EXHAUSTED 429 Too Many Requests Ratenbegrenzung oder Projektkontingent überschritten. Wiederholen Sie den Vorgang mit exponentiellem Backoff mit Jitter.
UNAVAILABLE 503 Service Unavailable Vorübergehende Netzwerkunterbrechung oder Neustart des Servers. Wiederholen Sie den Vorgang mit exponentiellem Backoff.
DEADLINE_EXCEEDED 504 Gateway Timeout Die Anfrage hat die konfigurierte RPC-Frist vor Abschluss überschritten. Wiederholen Sie den Vorgang mit einem erhöhten Client-RPC-Zeitlimit.

Zeitüberschreitung bei der MCP-Verbindung und Fehlerbehebung

Der MCP-Server für Entwicklerwissen ist ein Remote-Dienst, der unter https://developerknowledge.googleapis.com/mcp gehostet wird und über HTTPS (mit HTTP-POST oder Server-Sent Events) aufgerufen wird. KI‑Moderatoren und ‑Agents müssen Verbindungszeitüberschreitungen und Toolfehler angemessen verarbeiten.

Zeitüberschreitungen bei der Toolausführung

Wenn ein Agent search_documents, get_documents oder answer_query aufruft, kann es bei Tool-Aufrufen zu Zeitüberschreitungen kommen (z. B. 30 Sekunden), wenn Netzwerkverbindungen langsam sind.

So gehen Sie mit Zeitüberschreitungen bei der Toolausführung um:

  • Client-Time-outs konfigurieren: Legen Sie in der Konfiguration Ihres MCP-Hostclients Time-outs für die Toolausführung von 30 bis 60 Sekunden fest.
  • Netzwerkunterbrechungen behandeln: Wiederholen Sie fehlgeschlagene HTTP-Anfragen mit exponentiellem Backoff, wenn vorübergehende Netzwerkunterbrechungen oder HTTP 503-Antworten auftreten.
  • Fehlermeldungen prüfen: Parsen Sie standardmäßige JSON-RPC-Fehlermeldungen oder HTTP-Fehlerstatuscodes, um ungültige Argumente von Kontingentüberschreitungen zu unterscheiden.

Best Practices für die Kontingentverwaltung

Wenn Sie diese Best Practices befolgen, können Sie die API optimal nutzen und unerwartete Ratenbegrenzungen vermeiden:

  1. Abgerufene Dokumentinhalte im Cache speichern: Speichern Sie abgerufene Markdown-Dokumente lokal oder in einem Cache (z. B. Redis), wenn Sie Anwendungen erstellen, die häufig auf dieselben Seiten zugreifen.
  2. Batchabruf verwenden: Verwenden Sie documents.batchGet anstatt mehrere sequenzielle documents.get-Anfragen auszuführen.
  3. Abfragefelder optimieren: Fordern Sie nur die erforderlichen Antwortfelder an. Verwenden Sie dazu selektive Feldmasken (fields=results(parent,content)).
  4. Kontingentnutzung im Blick behalten: Verfolgen Sie die API-Anfrageraten im API-Dashboard der Google Cloud Console.

Weitere Informationen