API-Limits und ‑Kontingente

Die Google Ads API erzwingt Limits für API-Vorgänge, z. B. für die Anzahl der Vorgänge, die in einer einzelnen Mutationsanfrage gesendet werden können. In der folgenden Tabelle sind einige der wichtigsten Limits und Kontingente zusammengefasst.

Limits für API-Vorgänge pro Tag

Die Limits für die tägliche API-Nutzung basieren auf der Anzahl der API-Vorgänge , die von Ihrem Google Cloud-Projekt ausgeführt werden. API-Vorgänge sind die Gesamtsumme der Search und SearchStream Anfragen, der einzelnen Mutationsvorgänge und anderer Dienst anfragen. Die Limits für API-Vorgänge pro Tag hängen von der API-Zugriffsebene Ihres Google Cloud-Projekts ab. Im Leitfaden zu Zugriffsebenen und zulässiger Nutzung finden Sie die spezifischen Limits für API-Vorgänge für jede Zugriffsebene.

Anfragen, die diese Limits überschreiten, werden mit dem Fehler: RESOURCE_EXHAUSTED abgelehnt.

gRPC-Einschränkungen

Alle Google Ads API-Clientbibliotheken verwenden gRPC zum Generieren von Anfragen und Antworten. Standardmäßig ist die Nachrichtengröße in gRPC auf 4 MB begrenzt. In unseren Clientbibliotheken ist sie jedoch auf 64 MB festgelegt, um die Effizienz zu steigern.

Antworten dürfen dieses Limit nicht überschreiten. Beispielsweise kann eine Suchanfrage, die viele Felder enthält, eine Antwort mit einer Größe von mehr als 64 MB generieren. Um dieses Limit zu vermeiden, können Sie die Anzahl der ausgewählten Felder reduzieren oder Streamingverwenden. Senden Sie für Mutationen weniger Vorgänge pro Anfrage.

Anfragen, die dieses Limit überschreiten, führen nicht zu einem GoogleAdsError, sondern zu einem RESOURCE_EXHAUSTED (gRPC-Code 8 / HTTP 429)-Fehler. Eine Liste der gRPC-Fehlercodes und ‑Meldungen finden Sie hier.

Mutationsanfragen

Mutationsanfragen werden nicht nur auf das tägliche Kontingent für Vorgänge des Nutzers angerechnet, sondern dürfen auch nicht mehr als 10.000 Mutationsvorgänge pro Anfrage enthalten. Anfragen, die dieses Limit überschreiten, werden mit dem Fehler: TOO_MANY_MUTATE_OPERATIONS abgelehnt.

Im Folgenden werden zusätzliche Limits und Überlegungen für bestimmte Dienste und Anfragetypen beschrieben.

Suchanfragen

Eine Search oder SearchStream Anfrage wird auf das tägliche Kontingent für Vorgänge des Nutzers angerechnet. Eine SearchStream-Anfrage wird unabhängig von der Anzahl der Batches als ein API-Vorgang gezählt.

Paginierte Anfragen

Paginierte Anfragen (z. B. Anfragen, die ein gültiges next_page_token enthalten) werden nicht auf das tägliche Kontingent für Vorgänge des Nutzers angerechnet. Bei paginierten Anfragen, die ein abgelaufenes oder ungültiges Seitentoken enthalten, wird jedoch eine Ausnahme ausgelöst und sie werden auf das tägliche Kontingent für Vorgänge angerechnet.

Weitere Informationen zur Paginierung finden Sie unter In Ergebnissen suchen.

Andere Arten von Anfragen

Eine Anfrage, die keine Mutate, Search oder SearchStream Anfrage ist, wird auf das tägliche Kontingent für Vorgänge des Nutzers angerechnet.

Einige Beispiele für solche Anfragen:

• BatchJobService.ListBatchJobResults
• ConversionUploadService.UploadCallConversions
• ConversionUploadService.UploadClickConversions
• OfflineUserDataJobService.AddOfflineUserDataJobOperations
• OfflineUserDataJobService.CreateOfflineUserDataJob
• UserDataService.UploadUserData

Anfragen, die API-Ausnahmen zurückgeben

Anfragen, die mit einem GoogleAdsFailure abgelehnt werden, werden weiterhin auf das tägliche Kontingent für Vorgänge des Nutzers angerechnet.

Anfragen, die fehlschlagen, aber keinen GoogleAdsFailure, z. B. aufgrund eines Fehlers auf Netzwerkebene, werden nicht auf das tägliche Kontingent für Vorgänge des Nutzers angerechnet, da die Anfragen den Dienst nie erreichen. Ein Beispiel hierfür ist ein Fehler bei der Netzwerkverbindung.

Keyword-Planungsdienst

Aufgrund der Kosten und Komplexität unterliegen die folgenden Methoden des Keyword-Planungsdienstes anderen Limits als andere Arten von Anfragen.

• Begrenzt auf 1 Anfrage pro Sekunde und Kundennummer:

  • KeywordPlanIdeaService.GenerateKeywordIdeas
  • KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics
  • KeywordPlanIdeaService.GenerateKeywordForecastMetrics

  Anfragen, die diese Limits überschreiten, werden mit dem Fehler: RESOURCE_EXHAUSTED abgelehnt.

• 1 Abfrage pro Sekunde entspricht 60 Anfragen pro 60 Sekunden.

• Begrenzt auf 2 Anfragen pro Sekunde und Kundennummer:

  • KeywordPlanIdeaService.GenerateAdGroupThemes

Beachten Sie diese Limits, wenn Sie einen Keyword-Plan erstellen.

Dienst für Zielgruppeninformationen

Für die folgenden Methoden in AudienceInsightsService gelten bestimmte Kontingentlimits.

• Begrenzt auf ca. 200 Anfragen pro Tag und Kundennummer:
  • AudienceInsightsService.GenerateAudienceCompositionInsights
  • AudienceInsightsService.GenerateSuggestedTargetingInsights
• Begrenzt auf 2 Anfragen pro Sekunde und Google Cloud-Projekt:
  • AudienceInsightsService.GenerateTargetingSuggestionMetrics

Conversion-Upload-Dienst

• Begrenzt auf 2.000 Anruf- oder Klick-Conversions pro Anfrage:

  • ConversionUploadService.UploadCallConversions
  • ConversionUploadService.UploadClickConversions

  Anfragen, die diese Limits überschreiten, werden mit dem Fehler abgelehnt: TOO_MANY_CONVERSIONS_IN_REQUEST.

Dienst zum Hochladen von Conversion-Anpassungen

• Begrenzt auf 2.000 Conversion-Anpassungen pro Anfrage:

  • ConversionAdjustmentUploadService.UploadConversionAdjustments

  Anfragen, die diese Limits überschreiten, werden mit dem Fehler abgelehnt: TOO_MANY_ADJUSTMENTS_IN_REQUEST.

Conversion-Wert-Regeln

• Begrenzt auf 100.000 Conversion-Wert-Regeln pro Konto.

  Anfragen, die dieses Limit überschreiten, werden mit dem Fehler ResourceCountLimitExceededError.ACCOUNT_LIMIT abgelehnt.

Wenn für das Konto bereits ein ConversionValueRuleSet mit dem attachment_type CUSTOMER vorhanden ist, müssen Sie alle neuen Conversion-Wert-Regeln diesem Satz hinzufügen, damit sie aktiv werden. Wenn kein solcher Conversion-Wert-Regelsatz vorhanden ist, müssen Sie einen erstellen und Ihre Conversion Wert-Regeln hinzufügen, wie unter Regelsätze erstellen beschrieben.

Abrechnungs- und Kontobudgetdienste

• Mutationen können nur für Konten vorgenommen werden, die für die monatliche Rechnungsstellung konfiguriert sind.

  Anfragen, die dieses Limit überschreiten, werden mit dem Fehler: MUTATE_NOT_ALLOWED abgelehnt.

• Für Mutationsanfragen ist nur 1 Vorgang zulässig.

  Anfragen, die dieses Limit überschreiten, werden mit dem Fehler: TOO_MANY_MUTATE_OPERATIONS abgelehnt.

• Zwischen Änderungen am Kontobudget (AccountBudget oder AccountBudgetProposal) für dasselbe Konto sollten mindestens 12 Stunden liegen. Wenn Sie Änderungen vornehmen, bevor 12 Stunden vergangen sind, kann dies zu nicht wiederherstellbaren Fehlern führen, die nur von Ihrem Google Ads-Kundenbetreuer behoben werden können.

Einladungen zu Kundenkonten

Mit dem CustomerUserAccessInvitationService können neue Nutzer zu bestehenden Kundenkonten eingeladen werden. Da mit dieser Funktion E‑Mail-Einladungen an andere Nutzer gesendet werden, besteht die Gefahr des Missbrauchs. Daher gelten folgende Einschränkungen für das Verhalten:

• Nutzer können nicht mehr als eine ausstehende Einladung für dasselbe Kundenkonto erhalten. Wenn eine nachfolgende Anfrage gesendet wird, um eine Einladung an einen Nutzer zu senden, der bereits eine ausstehende Einladung hat, wird dieser Fehler zurückgegeben: EMAIL_ADDRESS_ALREADY_HAS_PENDING_INVITATION.

• Für Kundenkonten können nicht mehr als 70 ausstehende Einladungen gleichzeitig vorhanden sein. Wenn eine Anfrage gesendet wird, die dazu führt, dass dieser Wert überschritten wird, wird dieser Fehler zurückgegeben: PENDING_INVITATIONS_LIMIT_EXCEEDED.

Nutzerdaten

Nutzerdaten werden mit dem UserDataService und dem OfflineUserDataJobService verwaltet.

Jedes UserData-Objekt in einem create oder remove-Vorgang bezieht sich auf einen einzelnen Endnutzer. Das user_identifiers Feld in einem einzelnen UserData Objekt ist auf maximal 20 IDs begrenzt. Wenn dieses Limit in einem einzelnen UserData Objekt überschritten wird, wird der Fehler OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS oder UserDataError.TOO_MANY_USER_IDENTIFIERS zurückgegeben.

Umgang mit Nutzern mit mehr als 20 IDs

Wenn ein einzelner Endnutzer mehr als 20 IDs hat, die Sie hochladen müssen, sollten Sie diese IDs auf mehrere UserData-Objekte verteilen. Damit Google alle diese IDs demselben Endnutzer zuordnen kann, muss jedes UserData-Objekt für diesen Nutzer mindestens eine gemeinsame user_identifier enthalten, z. B. dieselbe hashed_email, hashed_phone_number oder third_party_user_id. Google verwendet diese gemeinsamen IDs, um die Informationen aus den separaten UserData-Vorgängen mit dem richtigen Endnutzerprofil zu verknüpfen und zusammenzuführen.

Wenn Sie auf personenbezogene Daten wie gehashte E-Mail-Adressen oder Telefonnummern angewiesen sind, müssen diese gemäß den Anforderungen der Google Ads API normalisiert und gehasht werden (SHA-256, Kleinbuchstaben, keine Leerzeichen), um Verknüpfungsfehler zu vermeiden.

Wenn ein Nutzer beispielsweise 30 E-Mail-Adressen hat, können Sie zwei UserData-Objekte senden, die eine gemeinsame third_party_user_id haben. Setzen Sie thirdPartyUserId und die E-Mail-Adressen 1 bis 19 in das erste Objekt, um das Limit von 20 IDs nicht zu überschreiten, und thirdPartyUserId und die E-Mail-Adressen 20 bis 30 in das zweite Objekt:

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_1" },
    // Hashed emails 2 through 18 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_19" }
  ]
}

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_20" },
    // Hashed emails 21 through 29 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_30" }
  ]
}

Das Gesamlimit für user_identifiers für alle Vorgänge in einer einzelnen AddOfflineUserDataJobOperationsRequest beträgt 100.000. Ein OfflineUserDataJob kann mehrere AddOfflineUserDataJobOperationsRequest-Aufrufe akzeptieren, bis zu einem empfohlenen Maximum von 1.000.000 Vorgängen pro Job. Bei synchronen Uploads mit UploadUserDataRequest (UserDataService.UploadUserData) ist jede Anfrage auf maximal 10 Vorgänge und 100 user_identifiers für die gesamte Anfrage begrenzt.

Andere Arten von Limits

Ein wiederkehrendes Feld, z. B. eine Liste von Vorgängen, das zu viele Elemente in einer Anfrage enthält, kann den Fehler: REQUEST_SIZE_LIMIT_EXCEEDED verursachen. Diese Fehlermeldung kann auch auf andere Probleme zurückzuführen sein.

Wenn Sie auf dieses Limit stoßen und Anfragen mit einem wiederkehrenden Feld senden, versuchen Sie, die Anzahl der Elemente im wiederkehrenden Feld zu reduzieren, indem Sie die Liste der Vorgänge auf mehrere Mutationsanfragen aufteilen.

Bei einer GAQL-Abfrage beträgt die maximale Anzahl von Elementen in einer IN-Klausel 20.000. Wenn Sie dieses Limit überschreiten, wird der FILTER_HAS_TOO_MANY_VALUES Fehler zurückgegeben.