Limits und Fehler

Tarifvoraussetzungen, Ratenlimits und die häufigsten Fehler (401, 403, 404, 422, 429 und mehr) samt Hinweis, was Sie jeweils tun.

Welchen Tarif brauche ich? #

API-Zugang. API und MCP setzen einen Tarif mit API-Zugang voraus. Admins haben ihn. Kostenlose Konten sehen die Einstellungsseite mit einem Upgrade-Hinweis.
Project Pro. Der Project-Pro-Pass (auch in jedem bezahlten Tarif enthalten) öffnet API und MCP nur für Ihre Projektseiten, Ihren eigenen Newsroom und Market: die discover_*-Tools, list_market_listings, create_market_listing, update_market_listing, pause_market_listing, die Änderungsanfragen von Market und whoami. Tokens können dann nur read:products, write:products, read:market und write:market tragen. SEO, Tag Manager, Media-Entwürfe und Content Autopilot brauchen API-Zugang (Pro und höher).
Search-Console- und GA4-Daten. Zum Lesen brauchen Sie die Tarifleistung für Search Insights und die eingerichtete Google-Verbindung im Workspace.
Änderungen im Tag Manager. Lesen nutzt dieselbe Tarifleistung wie Search Console. Für Änderungen brauchen Sie die Tag-Manager-Funktion (Teil des Tarifs Pro und höher).
Keywords. Tägliche Abfragen, getrackte Keywords und die Häufigkeit der Rank-Checks hängen vom Tarif ab; kostenlose Konten haben keine. whoami zeigt, was übrig ist.
Uptime und Berichte. uptime_status und list_reports liefern leere Listen, wenn Ihr Tarif die Funktion nicht enthält.

Ratenlimits #

Die Limits gelten pro Token: 60 Anfragen pro Minute beim Lesen und 20 pro Minute beim Schreiben (Änderungen in Tag Manager und Discover). Überschreiten Sie das, kommt 429 mit einem Retry-After-Header, der die Wartezeit in Sekunden nennt.

Der Google Tag Manager hat zusätzlich ein eigenes Kontingent für die ganze Plattform. Ist es knapp, antwortet ein Lesezugriff oder eine Änderung eventuell mit dem Status queued und einer change_id. Fragen Sie mit gtm_change_status ab, wann sie erledigt ist.

Das Fehlerformat #

Fehler kommen als JSON:

json

{ "error": { "code": "insufficient_scope", "message": "...", "details": {} } }

Achten Sie auf den code. Er ist stabil.

Häufige Fehler #

HTTP	Bedeutung	Was Sie tun
401 `unauthenticated`	Token fehlt, ist falsch, abgelaufen oder widerrufen.	Prüfen Sie den Header `Authorization: Bearer`. Erstellen Sie bei Bedarf einen neuen Token.
403 `insufficient_scope`	Dem Token fehlt der Scope.	Erstellen Sie einen Token mit dem Scope (siehe Token erstellen).
403 `plan_required`	Ihr Tarif hat keinen API-Zugang oder diese Funktion nicht.	Prüfen Sie Ihren Tarif.
404	Nicht gefunden oder nicht Ihres.	Prüfen Sie Site-Host, Slug oder ID. Fremde Daten sehen immer wie 404 aus.
404 `google_analytics_not_connected`	Für diese Site ist keine GA4-Property gewählt.	Wählen Sie eine unter SEO → Integrations.
409 `google_reconnect`	Ihre Google-Verbindung muss erneuert werden.	Verbinden Sie Google im Workspace neu.
409 `translation_live`	Sie wollten über den Agenten eine veröffentlichte Sprache bearbeiten.	Bearbeiten Sie sie im Workspace unter Languages.
409 `busy`	Eine andere Anfrage zur selben Sache läuft gerade.	Versuchen Sie es gleich noch einmal.
422	Validierung fehlgeschlagen, oder `action_failed`, wenn eine Änderung lief und scheiterte.	Lesen Sie die Meldung. Sie nutzt die Worte des Editors.
429 `rate_limited`	Zu viele Anfragen.	Warten Sie die Zeit aus `Retry-After` ab.

Weitere Codes, die Ihnen begegnen können:

google_scope_missing: Für eine Änderung, die sofort laufen würde, fehlt eine Google-Berechtigung. Ein Vorschlag oder eine Bestätigung funktioniert trotzdem. Erteilen Sie die Berechtigung in Ihrer Google-Verbindung.
invalid_url: Die Screenshot-Adresse war kein öffentliches https-Bild.
quota_reached: ein Limit Ihres Tarifs ist erreicht: das monatliche oder tägliche Newsroom-Kontingent, die aktiven Market-Anzeigen Ihres Tarifs oder das Limit für neue Inhalte (Project Pro: 30 pro Monat und 5 pro Tag für Briefs, neue Anzeigen und Seitenänderungen zusammen, im Web und per MCP).
limit_reached (429): Das Keyword-Limit Ihres Tarifs ist aufgebraucht. account_spend_cap (429): Ihr Konto hat das Keyword-Datenlimit dieses Monats erreicht.
provider_budget_reached (503): Keyword-Daten sind für alle vorerst pausiert. provider_not_connected (503) und provider_error (502) bedeuten, dass die Datenquelle nicht verfügbar ist. Versuchen Sie es später.
search_console_not_connected und gtm_not_connected (404): Search Console oder Google Tag Manager im Workspace unter SEO, Integrations verbinden.
publish_cap_reached: das Tageslimit automatischer Tag-Manager-Veröffentlichungen ist erreicht; stattdessen bestätigt der Inhaber die Veröffentlichung.

202 ist kein Fehler #

Änderungs-Tools antworten mit 200, wenn alles erledigt ist, und mit 202, wenn die Änderung ein Vorschlag ist, auf Ihre Bestätigung wartet (mit confirm_url) oder in der Warteschlange liegt. Siehe Modi und Freigaben.

Seitenweise Abruf #

Listen-Endpunkte liefern data und meta. Geben Sie meta.next_cursor als cursor mit, um die nächste Seite zu holen.

Wenn Sie nicht weiterkommen #

Lassen Sie Ihren Assistenten whoami aufrufen. Das zeigt Tarif, verbleibende Limits und die Scopes des Tokens und erklärt die meisten 403.