> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.hellodata.ai/llms.txt. # 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. > **Info** > > 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](/docs/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](mailto: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](mailto: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](mailto:support@hellodata.ai) for help." Your organization is paused (e.g. billing or compliance). **What to do:** * Contact [support@hellodata.ai](mailto: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](mailto: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](/docs/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:** ```json { "message": "Validation Failed", "details": { ... } } ``` **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](/docs/comparables), [Price Recommendations](/docs/price-recommendations), and [Property Details](/docs/property-details) guides. * If you’re unsure, follow the examples in those guides or contact [support@hellodata.ai](mailto: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:** ```json { "error": "Too many requests", "limit": 550, "retryAfter": 23 } ``` `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](/docs/rate-limits) and [Respecting Rate Limits](/docs/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: ```json { "message": "Something went wrong. We have been notified and are working on it. Please try again later." } ``` **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](mailto:support@hellodata.ai) with those details. * Check the [Changelog](/docs/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. |