Common Error Codes

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.

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.

”Your Organization has been paused. Contact support@hellodata.ai for help.”

Your organization is paused (e.g. billing or compliance).

What to do:

• Contact support@hellodata.ai to resolve and resume access.

”Permission denied”

You’re not allowed to access that resource.

What to do:

• 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.
• See Rate Limits and Respecting Rate Limits for examples (including Python and TypeScript).

500 Internal Server Error

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