FlowData

Welche Fehlermeldungen liefern die FlowData-APIs und was bedeuten sie?

Veröffentlicht am 05. November 2026

Wenn eine FlowData-Anfrage nicht klappt, verraten dir HTTP-Status und Antworttext fast immer die Ursache. Dieser Artikel sammelt die Meldungen, die in allen Bereichen gleich sind, und zeigt dir, woran du die Fehler der einzelnen Bereiche erkennst.

Erst den HTTP-Status prüfen

Die Fehlerantworten der Bereiche sehen unterschiedlich aus. Verlass dich in deiner Integration deshalb zuerst auf den HTTP-Status und lies erst danach den Text:

Bereich Form der Fehlerantwort
IP Geolocation {"status":"fail","message":"..."}
Maps {"success":false,"error":"...","details":{...}}
Email Verifier {"error":"Invalid email address"}
YouTube {"success":false,"error":"..."}
Medienverarbeitung {"error":{"code":"...","message":"...","details":{...},"type":"..."}}

Die Meldungen zur Anmeldung, zum Zugriff und zur Abrechnung weiter unten sind in allen Datenbereichen gleich. Die Medienverarbeitung liefert sie in ihrem eigenen Format. Unter https://api.flowdata.one/v1 bekommst du immer JSON zurück. Eine unbekannte Adresse beantwortet die API mit 404, eine falsche Methode mit 405.

401: Schlüssel fehlt oder ist ungültig

error Bedeutung und Lösung
API-Token erforderlich Es kam kein Schlüssel an. Er muss im Header Authorization: Bearer fd_... stehen. Andere Wege, etwa ein Parameter in der Adresse, werden nicht ausgewertet, auch wenn der Meldungstext einen „token“-Parameter erwähnt. Prüfe auch, ob zwischen Bearer und dem Schlüssel genau ein Leerzeichen steht.
Ungültiger API-Token Der Schlüssel ist unbekannt, abgelaufen oder widerrufen. Prüfe unter API-Schlüssel, ob er noch Aktiv ist und ob du ihn vollständig kopiert hast. Hast du ihn mit Neu erzeugen erneuert, gilt der alte Wert nur noch kurze Zeit.

Fehlgeschlagene Anmeldungen erscheinen nicht im Protokoll, weil FlowData ohne gültigen Schlüssel kein Team zuordnen kann.

402: Guthaben oder Limit reicht nicht

In den Datenbereichen IP Geolocation, Maps, Email Verifier und YouTube antwortet FlowData mit HTTP 402, wenn die Anfrage nicht gedeckt ist. Die Antwort sieht so aus:

{"error":{"message":"...","type":"billing_error","code":"insufficient_quota"}}
code Bedeutung und Lösung
insufficient_quota Das Guthaben reicht nicht. Lade es auf. Rechnet dein Team nach Verbrauch ab, ist der Kreditrahmen ausgeschöpft, dann wende dich an den Support.
spend_limit_exceeded Das Ausgabenlimit des Teams oder das Limit dieses Schlüssels ist für den laufenden Monat erreicht. Hebe es an oder warte auf den nächsten Monat.

Medienaufträge melden dieselben Ursachen mit HTTP 429 und diesen Codes, zusammen mit dem Header Retry-After.

Eine Antwort 503 bedeutet, dass die Abrechnung gerade kurz nicht erreichbar ist. Versuch es in Kürze erneut.

403: Zugriff verweigert

code oder error Bedeutung und Lösung
flowdata_access_denied Der Person, der der Schlüssel gehört, wurde der Zugriff auf FlowData entzogen. Gib ihn zurück oder nutze einen anderen Schlüssel.
Kein Teamzugriff Die Person, der der Schlüssel gehört, ist nicht mehr im Team. Leg einen neuen Schlüssel an.
insufficient_key_scope Du nutzt den FlowData-Schlüssel für einen Endpunkt, der nicht zu FlowData gehört, etwa FlowCRM. Dafür brauchst du einen Schlüssel aus deinem Profil.
billing_suspended Die FlowData-Abrechnung deines Teams ist gesperrt. Wende dich an den Support.
forbidden mit flowdata_key_required in details Du rufst die Medienverarbeitung mit einem FlowSuite-Schlüssel auf. Dort brauchst du einen FlowData-Schlüssel.

Mehr zu den ersten beiden Fällen steht in FlowData im Team freigeben, zum letzten in FlowSuite-Schlüssel umstellen.

429: zu viele Anfragen

Jeder Schlüssel darf pro Minute eine begrenzte Zahl von Anfragen stellen. Wird die Grenze erreicht, antwortet FlowData mit HTTP 429, bis die Minute um ist. Der Header Retry-After der Antwort nennt dir die Wartezeit in Sekunden. So gehst du damit um:

  1. Warte die Zeit aus Retry-After ab und wiederhole die Anfrage. Wartet deine Integration bei jedem weiteren 429 etwas länger, bevor sie es erneut versucht, löst sich das meist von selbst.
  2. Fasse Abfragen zusammen, wo es geht. Bei IP Geolocation zählt eine Batch-Abfrage mit bis zu 100 Adressen für diese Grenze als eine Anfrage. Berechnet wird sie aber je erfolgreichem Eintrag.
  3. Speichere Ergebnisse, die sich selten ändern, für kurze Zeit in deiner Anwendung, statt sie bei jedem Seitenaufruf neu abzufragen. Beachte bei Maps den Nutzungshinweis in der Antwort (attribution), der dauerhaftes Speichern ausschließt.

Ein anderer 429 betrifft fehlgeschlagene Anmeldungen: Schickt eine Adresse in kurzer Zeit viele Anfragen mit falschem oder fehlendem Schlüssel, antwortet FlowData eine Weile mit Zu viele fehlgeschlagene Authentifizierungsversuche. Korrigiere den Schlüssel und warte einen Moment.

Die Medienverarbeitung erlaubt 600 Anfragen und 60 neue Aufträge pro Minute je Schlüssel. Weitere Grenzen stehen in Medienauftrag starten.

Fehler der einzelnen Bereiche

Die Meldungen zu Parametern, „nicht gefunden“ und Serverfehlern unterscheiden sich je Bereich. Du findest sie in diesen Artikeln:

Gut zu wissen

Alle Anfragen mit gültigem Schlüssel stehen im Protokoll des jeweiligen Bereichs, auch abgelehnte mit 400, 402, 404, 422 oder 429. Stell den Filter auf Fehlgeschlagen und öffne mit dem Augensymbol die genaue Fehlerantwort. Wie das geht, steht in Statistik und Protokoll.

War dieser Artikel hilfreich?

Zurück zu Erste Schritte & API-Schlüssel