Error Codes

All errors follow a consistent format with an HTTP status code and a detail message.

Error Format

Error Response
{
  "detail": "Human-readable error message"
}

Status Codes

400Bad Request

Missing or invalid parameters. Check the error message for details.

401Unauthorized

Missing or invalid API key. Ensure you're passing the X-API-Key header.

403Forbidden

API key is valid but lacks permission. Usually means email not confirmed or endpoint not available on your plan.

404Not Found

The requested property or resource doesn't exist.

409Conflict

Resource already exists (e.g., email already registered).

429Too Many Requests

Rate limit exceeded. Check the rate limit headers and retry after backing off.

502Bad Gateway

Upstream data source (Census, FEMA, etc.) is temporarily unavailable. Retry in a few seconds.

Best Practices

  • Always check the HTTP status code before parsing the response body.
  • For 429 errors, implement exponential backoff.
  • For 502 errors, retry after a few seconds — the upstream source is likely temporarily unavailable.
  • Display the detail message to help debug issues.