Errors & Rate Limits

Common errors

Status	Meaning	Example
`400`	Invalid filter, column, cursor, or request body	`{ "error": "state required" }`
`401`	Missing or invalid API key	`{ "error": "authentication required" }`
`402`	Monthly contact allowance exceeded	See below
`403`	State or operation not allowed	`{ "error": "state not allowed" }`
`409`	Export download requested before it is ready	`{ "error": "export not ready" }`
`410`	Export download has expired	`{ "error": "export expired" }`
`429`	Request rate or daily preview limit exceeded	See below
`5xx`	Service could not complete the request	`{ "error": "query failed" }`

Preview limit

The API allows 500 preview rows per organization, state, and UTC day. When the limit is reached, exports remain available and the API returns:


{
  "error": "preview_cap_exceeded",
  "message": "You've reached today's free preview limit of 500 rows for this state. Previews reset tomorrow — exports are unaffected.",
  "resets": "2026-07-18"
}

Monthly allowance


{
  "error": "quota_exceeded",
  "state": "TX",
  "remaining": 1200,
  "requested": 50000,
  "reset_date": "2026-08-01"
}

Request rate

If the request rate is exceeded, wait before retrying. A 429 response can include:


{
  "error": "rate_limited",
  "message": "rate limit exceeded"
}