FlowData

What do the FlowData API error messages mean?

Published on 10. November 2026

When a FlowData request fails, the HTTP status and the response text almost always tell you why. This article collects the messages that are the same across all areas and shows how to recognize the errors of each individual area.

Check the HTTP status first

The error responses of the areas look different from one another, so have your integration rely on the HTTP status first and read the text after that:

Area Error response format
IP Geolocation {"status":"fail","message":"..."}
Maps {"success":false,"error":"...","details":{...}}
Email Verifier {"error":"Invalid email address"}
YouTube {"success":false,"error":"..."}
Media processing {"error":{"code":"...","message":"...","details":{...},"type":"..."}}

The messages about authentication, access and billing below are the same in all data areas. Media processing returns them in its own format. Under https://api.flowdata.one/v1 you always get JSON back. An unknown address is answered with 404 and a wrong method with 405.

401: key missing or invalid

The error field is always in German, so the values below are shown exactly as you'll see them.

error Meaning and fix
API-Token erforderlich No key was received. It must be in the Authorization: Bearer fd_... header. Other ways, such as a parameter in the URL, are not evaluated, even though the message text mentions a "token" parameter. Also check that there is exactly one space between Bearer and the key.
Ungültiger API-Token The key is unknown, expired or revoked. Check under API keys that it is still Active and that you copied it completely. If you renewed it with Regenerate, the old value only works for a short time.

Failed logins don't appear in the log, because without a valid key FlowData can't tell which team to assign them to.

402: balance or limit not sufficient

In the data areas IP Geolocation, Maps, Email Verifier and YouTube, FlowData answers with HTTP 402 when a request isn't covered. The response looks like this:

{"error":{"message":"...","type":"billing_error","code":"insufficient_quota"}}
code Meaning and fix
insufficient_quota The balance isn't enough. Top it up. If your team is billed by usage, the credit line is used up, so contact support.
spend_limit_exceeded The team's spend limit or this key's limit has been reached for the current month. Raise it or wait for the next month.

Media jobs report the same causes with HTTP 429 and these codes, along with the Retry-After header.

A 503 response means billing is briefly unavailable. Try again shortly.

403: access denied

code or error Meaning and fix
flowdata_access_denied The person the key belongs to has had their FlowData access removed. Restore it or use a different key.
Kein Teamzugriff The person the key belongs to is no longer in the team. Create a new key.
insufficient_key_scope You're using the FlowData key for an endpoint that isn't part of FlowData, such as FlowCRM. For that you need a key from your profile.
billing_suspended Your team's FlowData billing is suspended. Contact support.
forbidden with flowdata_key_required in details You're calling media processing with a FlowSuite key. It needs a FlowData key.

Read more about the first two cases in Sharing FlowData with your team, and about the last one in Replacing FlowSuite keys.

429: too many requests

Each key may send a limited number of requests per minute. Once it hits the limit, FlowData answers with HTTP 429 until the minute is over. The response's Retry-After header gives you the wait in seconds. Here's how to handle it:

  1. Wait for the time given in Retry-After and retry the request. If your integration waits a little longer after each further 429 before trying again, it usually sorts itself out.
  2. Combine lookups where you can. For IP Geolocation, a batch request with up to 100 addresses counts as one request against this limit. It's billed per successful entry, though.
  3. Store results that rarely change for a short time in your application instead of requesting them again on every page view. For Maps, note the usage notice in the response (attribution), which rules out permanent storage.

A different 429 relates to failed logins: if one address sends many requests with a wrong or missing key in a short time, FlowData answers for a while with Zu viele fehlgeschlagene Authentifizierungsversuche. Fix the key and wait a moment.

Media processing allows 600 requests and 60 new jobs per minute per key. Further limits are in Starting a media job.

Errors of the individual areas

Messages about parameters, "not found" and server errors differ by area. You'll find them in these articles:

Good to know

All requests with a valid key are in the log of their area, including refused ones with 400, 402, 404, 422 or 429. Set the filter to Failed and use the eye icon to open the exact error response. Statistics and request log shows you how.

Was this article helpful?

Back to Getting started & API keys