Troubleshooting and error handling

Need help with the metadata endpoints? Look no further.

HTTP Status Codes

Code	Meaning	Action
200	Success	Process the response
400	Bad request	Check query syntax
401	Unauthorized	Verify API token
403	Forbidden	Check permissions
404	Not found	Verify resource ID
429	Too many requests	Implement rate limiting
500	Server error	Retry after delay

Dataset not found

• Symptom: See response below.

{
  "success": false,
  "error": {
    "__type": "Not Found Error",
    "message": "Not found"
  }
}

• Likely cause: Incorrect dataset ID or name.
• Fix: Verify the dataset ID or name. Use package_search to find the correct identifier.

No results

• Symptom: No results returning from package_search endpoints even though the query should return packages.
• Likely cause: Incorrect search query.
• Fix: Review your Solr query syntax. Ensure quotes and operators are properly formatted.

Rate limiting

• Symptom: 429 error code
• Likely cause: Using API calls more than 60 times per minute.
• Fix: HDX implements rate limiting to ensure service stability. Anonymous requests are limited to prevent abuse. Authenticated requests have higher limits for registered users. For best practices, we recommend caching results when possible and adding delays between bulk requests.