error-recovery

A 404 usually means the resource UUID changed. Call package_show with the dataset slug to list current resource IDs, or run catalog-refresh.py to regenerate the local endpoint registry with up-to-date UUIDs.

Empty results usually come from case-sensitive field names, inconsistent borough name formats, or mismatched date formats. Inspect actual field names with datastore_search limit=0 and use LIKE patterns with wildcards instead of exact matches.

Wait 10-30 seconds and retry, add LIMIT to every query, and space sequential calls 2-3 seconds apart. For simple queries on large datasets, use the datastore_search filters parameter instead of SQL, which is less likely to be throttled.

The DataStore API silently truncates responses at a 32,000-row default limit. Paginate with LIMIT and OFFSET ordered by _id until fewer rows than the limit are returned, or use GROUP BY to aggregate server-side.

A 409 means the SQL query is too complex for server-side processing, common with GROUP BY on multi-million-row datasets like 311 or crime data. Narrow the date range first, then aggregate, or fall back to the filter-based datastore_search endpoint.

Most data is UTF-8, but garbled characters indicate Latin-1 decoding. For CSV downloads use encoding utf-8-sig to handle BOM, and accented characters work directly in SQL WHERE clauses.