API-Fehler und Ratenbegrenzungen

Fehler geben { "error": { "code": "…", "message": "…", "details": … } } mit passendem HTTP-Status zurück.

• 400 invalid_parameter: Ein Abfrageparameter wie since, until oder outcome ist fehlerhaft.
• 401 unauthorized: Fehlender, ungültiger oder widerrufener Schlüssel.
• 403 plan_required: API-Zugriff erfordert einen Scale-Plan oder höher für mindestens eine Website.
• 403 insufficient_scope: Der Schlüssel ist nur lesbar.
• 429 cooldown, concurrency, daily_quota, monthly_quota, competitor_quota oder host_busy: Ein SEO-Audit-Limit greift; siehe retry_at und Retry-After.
• 403 org_suspended: Kontaktieren Sie den Support.
• 404 not_found: Die Ressource existiert nicht in Ihrer Organisation.
• 409 conflict: Der Suchbegriff existiert bereits für dieses Land und Gerät.
• 422 validation_failed / limit_exceeded / plan_required / project_unverified: Siehe Nachricht und Details.
• 429 rate_limited: Warten Sie Retry-After Sekunden.
• 500 internal_error: Versuchen Sie es erneut; kontaktieren Sie den Support, wenn das Problem weiterhin besteht.
• 503 unavailable: Die API ist vorübergehend nicht verfügbar; versuchen Sie es mit Backoff erneut.

Ratenbegrenzungen

120 Anfragen pro Minute pro Schlüssel. Eine 429-Antwort enthält Retry-After: 60. Jede Anfrage wird dem Schlüssel zugeordnet, und die letzte Nutzungszeit des Schlüssels (maximal einmal pro Minute aktualisiert) wird in Einstellungen → API-Schlüssel angezeigt.

Planlimits

Das Hinzufügen oder Ändern von Begriffen senkt Ihre Zahlen niemals stillschweigend: Wenn eine Anfrage das Suchbegriff- oder Klicks-pro-Tag-Limit der Website überschreiten würde, schlägt sie mit 422 fehl und zeigt an, wie viel noch übrig ist.