Troubleshooting and error handling

Need help with the HAPI? Look no further.

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.