For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
When calling the HelloData API, you may receive HTTP error responses. This page explains the most common status codes, their typical causes, and concrete steps to resolve them.
All error responses use a JSON body. Check the message (and, when present, details) fields for human‑readable descriptions.
401 Unauthorized
”Requires authentication”
The request did not include an API key.
What to do:
Add your API key to the request (in the x-api-key header). See Authentication for how to get and use it.
If a developer or tool is making the calls for you, ask them to include the API key in every request.
”Bad credentials”
Your API key was rejected.
What to do:
Check your API key: Open the HelloData platform → API section. Copy the key again and ensure there are no extra spaces, missing characters, or typos when you paste it.
Regenerate if needed: If you’re unsure whether the key is still valid, create a new one in the API section and use that.
Only some endpoints fail? You might actually be hitting 403 Forbidden (see below)—your plan may not include that endpoint. Contact support@hellodata.ai to confirm.
403 Forbidden
”Forbidden” with details
Your API key works, but your plan does not include access to that endpoint.
Example details: "The token provided does not have access to RentSourceExpenseBenchmarks. Please contact the HelloData support team to enable it."
What to do:
Contact support@hellodata.ai and say which endpoint or feature you need (you can paste the details message). We can add it to your subscription.
Double-check you’re using the right API key and that your account is in good standing. If it still fails, contact support@hellodata.ai.
404 Not Found
The requested resource does not exist or is not available to you.
What to do:
Property: Use Property Search to discover valid IDs. Note: private (custom-created) properties are not in the search index. After creating a property via POST /property, store and use the returned ID directly; do not expect it to appear in search results.
Dataset / report: Double-check the URL or ID you are requesting. Ensure the resource was created under the same account and has not been deleted.
422 Validation Failed
The request body or parameters failed validation. The response includes a details object (often field‑level) describing what is wrong.
Example:
1
{
2
"message": "Validation Failed",
3
"details": { ... }
4
}
What to do:
Check the details in the error—it lists which fields are wrong. Fix those and try again.
Comparables, pricing, expense benchmarks: Use the full property data from GET /property/{id} as your request body. Don’t filter or remove units or their IDs; pass the complete response. See the Comparables, Price Recommendations, and Property Details guides.
If you’re unsure, follow the examples in those guides or contact support@hellodata.ai.
429 Too Many Requests
You have exceeded the rate limit. The API allows 550 requests per minute per API key (rolling 60‑second window). Property search and a few other routes are not rate limited.
Response body:
1
{
2
"error": "Too many requests",
3
"limit": 550,
4
"retryAfter": 23
5
}
retryAfter is how many seconds to wait before trying again. Occasionally you may see "Too many requests (fallback)" without retryAfter—wait about a minute, then retry.
What to do:
Wait, then retry: Wait the number of seconds shown as retryAfter (or in the RateLimit header) before making more requests.
Slow down: You’re sending too many requests too quickly. Add delays between calls. If a script or tool is calling the API, reduce how often it runs or how many requests it sends at once.
The server encountered an unexpected error. Responses use a generic message such as:
1
{
2
"message": "Something went wrong. We have been notified and are working on it. Please try again later."
3
}
What to do:
Try again in a few seconds. Temporary glitches often clear up on their own.
If it keeps happening on the same request: note the exact URL and what you sent (e.g. property ID, parameters), then contact support@hellodata.ai with those details.
Check the Changelog for known issues or recent changes.
Quick reference
Code
Meaning
Next steps
401
Missing or invalid API key
Add your API key to the request, or check/copy it again in the platform (API section). If only some endpoints fail, see 403 or contact support.
403
Key works but plan does not include this endpoint
Contact support to add the endpoint or feature to your subscription.
404
Resource not found
Check the ID or URL; use Property Search for properties. For custom-created properties, store and use the ID returned when you created them.
422
Request format or data invalid
Fix the fields listed in details; for comparables/pricing, use the full property data from GET /property/{id}.
429
Too many requests
Wait the seconds shown in the error, then slow down your requests (add delays between calls).
500
Server error
Retry after a few seconds. If it keeps failing, contact support with the URL and what you sent.
