Errors and Status Codes

​

Error envelope

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "state must be a 2-letter code",
    "request_id": "req-123"
  }
}

​

Status code rules

​

Search endpoint

• 200: property match found
• 404: no match found (including fuzzy below threshold)
• 400: request validation failure

​

Property endpoints (/permits, /profile)

• 200: valid property_id and matching permit rows found
• 400: malformed property_id format or invalid query params
• 404: syntactically valid property_id but no matching rows in permit source

​

Gateway-originated responses

• 403: missing/invalid API key
• 429: throttle/quota exceeded

​

Request IDs

• Service responses include X-Request-ID.
• Error envelopes include error.request_id for support/debugging.