API Error Handling - Shovels Documentation

For comprehensive error handling documentation, see the API Introduction - Error Handling section. This article covers the most common scenarios.

Most Common Issue: 422 Errors

A 422 error typically means you’re missing a required parameter—usually a geo_id. Solution: Resolve your address first using the Address Search endpoint, then use the returned geo_id in your permit query. See 422 error explained for details.

Empty Results vs Errors

An empty items array with a 200 response is not an error—it means your query was valid but no matching data exists.

{
  "items": [],
  "size": 50,
  "next_cursor": null,
  "total_count": { "value": 0, "relation": "eq" }
}

Quick Reference

Code	Meaning	Action
200	Success (may be empty)	Check `items` array
400	Bad request	Review request format
401	Unauthorized	Check API key
422	Missing/invalid parameter	See 422 guide
500	Server error	Contact support@shovels.ai

Full Documentation

For complete error handling details, response code explanations, and troubleshooting tips, see:

​Most Common Issue: 422 Errors

​Empty Results vs Errors

​Quick Reference

​Full Documentation

​Related Articles

Most Common Issue: 422 Errors

Empty Results vs Errors

Quick Reference

Full Documentation

Related Articles