Surfer API Fehlerbehebung

Referenztabelle:

Mögliche Probleme, die bei der Nutzung der API auftreten können:

1. Die Anfrage liefert eine generische HTML-Antwort

Die in der Anfrage angegebene URL ist ungültig und entspricht keinem API-Endpunkt.

2. Jede Anfrage liefert einen 401 Unauthorized mit der Meldung „Access denied."

Der angegebene API-Key ist falsch, fehlt, oder dein Plan unterstützt keine API-Anfragen. Denk daran, dass der Header „Key" ausdrücklich „API-KEY" heißen muss.

3. Jede Anfrage liefert einen 403 Forbidden mit der Meldung „Access denied."

Dein aktueller Plan unterstützt keine API. Überprüfe deinen aktuellen Plan in den App-Einstellungen und vergleiche ihn mit den verfügbaren Plänen mit API auf unserer Preisseite.

4. POST-Anfragen liefern einen 422 Unprocessable Entity mit der Meldung „Quota exceeded"

• Audit und Content Editor:

Das bedeutet, dass du das Nutzungslimit für dieses Tool in deinem aktuellen Abrechnungszeitraum erreicht hast.

• SERP Analyzer:

Du hast dein tägliches Kontingent überschritten (standardmäßig 100 Abfragen/Tag). Du kannst entweder warten oder dich an unser Vertriebsteam wenden, um die Limits mit einem individuellen Enterprise-Plan zu erweitern.

5. POST-Anfragen liefern einen 400 Bad Request mit der Meldung „Internal server error"

Deine Anfrage enthält einen Syntaxfehler, zum Beispiel ein fehlendes Komma.

6. POST-Anfragen liefern einen 422 Unprocessable Entity mit einer JSON-Meldung

Deine Anfrage enthält höchstwahrscheinlich nicht die erforderlichen Parameter (z. B. fehlende Keywords), oder die Abfrage ist fehlerhaft aufgebaut (es wurde ein String statt eines Arrays angegeben).

7. GET-Anfragen für CE-Inhalte liefern einen 500 Internal Server Error

Das bedeutet, dass für die Abfrage kein Content gespeichert ist. Höchstwahrscheinlich handelt es sich um eine leere Abfrage, die noch nie über die App aufgerufen wurde.

8. GET SERP Analyzer search_results Anfragen führen zu 404 Not found mit der Meldung "Not found."

Die ID, die Sie in der URL Ihrer Anfrage angegeben haben, ist falsch, oder diese ID gehört nicht zu dem Konto, das mit diesem API-Schlüssel verknüpft ist.

9. GET SERP Analyzer search_results Anfragen führen zu 200 OK, aber die meisten oder einige Zeilen enthalten leere Strings

Dies bedeutet, dass die Abfrage nicht alle erforderlichen Berechnungen abgeschlossen hat.

Sie können die 3. Spalte "state" referenzieren, um den Status jedes Konkurrenten-Crawls zu sehen.

Ähnlich wie bei regulären Abfragen:

• "completed" - Crawl wurde erfolgreich durchgeführt, die vorhandenen Daten basieren auf dem Inhalt, der uns bereitgestellt wurde (enthält keine leeren Werte, Standardwert ist "0")

• "scheduled" - Crawl wird noch verarbeitet (enthält leere Strings)

• "failed" - Crawl wurde erfolglos beendet - höchstwahrscheinlich wurden wir entweder blockiert oder es kam zu einem Timeout beim Versuch, auf diese URL zuzugreifen (enthält leere Strings)

10. GET SERP Analyzer prominent_terms Anfragen führen zu 404 Not found mit der Meldung "Not found"

Die ID, die Sie in der URL Ihrer Anfrage angegeben haben, ist falsch, oder diese ID gehört nicht zu dem Konto, das mit diesem API-Schlüssel verknüpft ist.

Wenn Sie sicher sind, dass die ID korrekt ist, dann entweder:

• Diese Abfrage wird noch verarbeitet (aufgelistet als "scheduled" vom Endpunkt exports/csv/serp_analyzer)

oder

• Wir konnten keine prominenten Phrasen für diese bestimmte Abfrage finden, höchstwahrscheinlich aufgrund mangelnder ausreichender schriftlicher Inhalte bei SERP-Konkurrenten.

11. JEDE Anfrage, die zu 429 Too Many Requests führt

Sie haben das Ratenlimit überschritten. Alle Endpunkte haben ein Standardlimit von 10 Anfragen/Sek, außer für SERP-Batch: 10 Anfragen/Min. Überprüfen Sie den Retry-After-Header in der Antwort, um zu sehen, wie lange Sie warten müssen, und versuchen Sie es dann erneut. Implementieren Sie für automatisierte Workflows exponentielles Backoff. Wenn Sie dies konsistent erreichen, überprüfen Sie Ihre Anfragehäufigkeit oder kontaktieren Sie den Support.

12. POST führt zu 406 Not Acceptable

Beachten Sie, dass dies nur für v2 gilt. Das angeforderte Antwortformat ist nicht verfügbar. Dies bedeutet normalerweise, dass ein Accept-Header mit einem nicht unterstützten Wert enthalten war. Entfernen Sie ihn oder setzen Sie ihn auf application/json.

13. JEDE Anfrage → 404 Not Found (falsche Basis-URL)

Beachten Sie, dass dies sich von der SERP-spezifischen 404 oben unterscheidet. Wenn Sie einen 404 bei einem Nicht-SERP-Endpunkt erhalten, ist Ihre Basis-URL wahrscheinlich falsch. Stellen Sie sicher, dass Sie folgende URL verwenden:

• v1: https://app.surferseo.com/api/v1/

• v2: https://app.surferseo.com/api/v2/

Nicht api.surferseo.com oder surferseo.com/api/… oder eine andere Variation.

14. POST → 413 Content Too Large

Ihr Request-Body überschreitet das Größenlimit. Am häufigsten beim AI Detector (max. 100.000 Zeichen) und Humanizer (mindestens 128 Zeichen, aber sehr große Eingaben können abgelehnt werden). Reduzieren Sie Ihre Eingabe und versuchen Sie es erneut.

15. JEDE Anfrage → 415 Unsupported Media Type

Ihre Anfrage verwendet einen nicht unterstützten Content-Type-Header. Alle Anfragen müssen Content-Type: application/json verwenden.

Zusätzliche Ressourcen:

Einführung in die Surfer-API
Surfer-API-Dokumentation (v1)
Surfer-API-Dokumentation (v2)
Anwendungsbeispiele für die Surfer-API