{ "message": "..." } or { "error": "..." }. Some endpoints answer with a bare status and no body at all, so read the status first and treat the body as a hint.
Failing to resolve a location is reported as
400, 401 or 404 depending on the endpoint. Treat all three the same way: the location id is wrong, or your key does not cover it.Messages worth recognising
403 { "error": "Invalid API key" }
403 { "error": "Invalid API key" }
Every credential refusal answers identically: unknown key, revoked key, expired key, wrong IP address, or a location the key does not cover. Work down the checklist in Authentication.
400 "Please include count, page and sorting query parameters."
400 "Please include count, page and sorting query parameters."
The visitor and registered-visitor lists require paging parameters. Add
count and page — and, on registered visitors, at least one sorting[field].400 { "message": "TRIAL_EXPIRED" }
400 { "message": "TRIAL_EXPIRED" }
The location is on an expired trial. Data endpoints stay closed until it is on a paid plan.
400 { "message": "Dataset too large." }
400 { "message": "Dataset too large." }
The visitor export is capped at 200 rows per call. Pass
count=200 with a page, or narrow the export with filters.400 { "message": "No data." }
400 { "message": "No data." }
The export matched no visitors. Not a failure — there was simply nothing to write.
429 "Too many invalid API key attempts from this IP"
429 "Too many invalid API key attempts from this IP"
Thirty refused credentials from one address inside fifteen minutes. Stop retrying, fix the key, and wait out the window — retrying with the same broken key only extends it.
A note on 200s
A handful of older endpoints answer200 with a message body instead of an error status — for example { "message": "company not found" } or { "message": "No Known Visitor found!" }. When you expect an object and get a body with only a message key, treat it as “not found”.
Retrying
500is worth one or two retries with a short backoff.400,401,403and404never become successful on retry. Fix the request.429needs you to stop entirely for the window — further attempts keep it open.