> For the complete documentation index, see [llms.txt](https://docs.humdata.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.humdata.org/build/hdx-apis/hapi/troubleshooting-and-error-handling.md).

# Troubleshooting and error handling

### Pagination

* **Symptom: Your result set stops at exactly 10,000 records.**
* Likely cause: HAPI returns at most 10,000 records per call. A query with more matches than that is truncated without an error, so the missing records are easy to miss.
* Fix: Page through the results with limit and offset, and loop until a page returns fewer records than your limit. Keep the same query parameters across every page so the result set stays consistent. See Pagination under How to query HAPI for the full explanation, and Examples and use-cases for a ready-to-run loop.

### Missing or invalid app identifier

* **Symptom: Your request is rejected with a 403 or returns an error about the app identifier.**
* Likely cause: The app\_identifier parameter is missing, malformed, or was not URL encoded.
* Fix: Generate an identifier as shown in How to query HAPI and include it on every request, either as app\_identifier or as the header X-HDX-HAPI-APP-IDENTIFIER.

### Too many results, or the wrong ones

* **Symptom: A text filter returns more rows than expected.**
* Likely cause: Filters on text fields are case insensitive and match as wildcards, so location\_name=Mali also matches Somalia.
* Fix: Filter on a code field such as location\_code for exact matches.

### No results

* **Symptom: A successful request returns an empty data array.**
* Likely cause: A filter value that does not match, or an offset beyond the end of the data.
* Fix: Remove filters and request a small limit to confirm data exists, then add filters back one at a time. Check the availability dashboard to confirm the indicator is available for that location.

### Wrong theme or code

* **Symptom: 404 Not Found.**
* Likely cause: A mistyped theme path. A code that does not exist, such as an unknown ISO3 or p-code, does not cause a 404. That request succeeds and returns an empty data array, so see No results above.
* Fix: Confirm the theme path against the API reference page, and confirm codes using the metadata sub-categories, for example metadata/admin1.

### JSON versus CSV

* **Symptom: You expected a file but received JSON, or the reverse.**
* Fix: Set output\_format=csv to download a CSV, or use the default output\_format=json for JSON.

### Rate limiting

* **Symptom: Your request is rejected with a 429.**
* Likely cause: HAPI allows roughly 60 requests per minute. A retry loop with no delay between attempts, or an app identifier shared across several users or systems, will reach that ceiling quickly.
* Fix: Keep your request rate under the limit, add a delay between retries rather than retrying immediately, and generate your own app identifier rather than reusing one copied from an example.

<br>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.humdata.org/build/hdx-apis/hapi/troubleshooting-and-error-handling.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.