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:
- Wait for the time given in
Retry-Afterand retry the request. If your integration waits a little longer after each further 429 before trying again, it usually sorts itself out. - 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.
- 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:
- IP Geolocation: Looking up an IP address and Batch lookup
- Maps: Maps finds nothing: common mistakes
- Email Verifier: Checking an email address
- YouTube: Channel not found or wrong channel
- Media processing: Media job status and errors
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.