Enrich CKAN error responses with actionable hints for LLM clients

[aborruso]

When a CKAN API call returns 4xx/5xx, the server currently surfaces the raw upstream error. For LLM clients this is often unhelpful — the LLM cannot tell whether to retry, switch portal, or abandon the path.

Pattern

Wrap upstream errors with a short, actionable hint the LLM can act on.

Concrete cases

• ckan_datastore_search / ckan_datastore_search_sql against a portal without the DataStore extension → hint: "This portal does not expose the DataStore API. Try a portal with DataStore enabled, e.g. https://dati.comune.messina.it or https://open.canada.ca/data."
• ckan_package_show with an invalid id → hint: "Dataset not found. Use ckan_package_search to discover valid ids on this portal."
• Timeout / 5xx from upstream → hint: "Portal unreachable. Retry later, or call ckan_status_show to check portal health."
• ckan_organization_show / ckan_group_show with an invalid name → hint suggesting the corresponding *_list / *_search tool.

Implementation

Centralize error enrichment in src/utils/http.ts (or a small dedicated layer) so all tools benefit without per-tool boilerplate. Map error.__type / HTTP status to a catalog of hints.

References

• Inspired by: fix(tabular): handle Tabular API 4xx/5xx with LLM hints datagouv/datagouv-mcp#94