Errors and pagination
Source-reviewed draft; deployment and release verification pending.
Draft — source-reviewed on 22 October 2026. No live rate-limit or deployment verification was performed.
Successful data operations return their documented JSON DTO directly with status 200. There is no universal { "success": true, "data": ... } wrapper in this public API. Image operations return binary JPEG data.
Error shape
Errors use a top-level detail value. It can be a message string or an array of field errors:
{"detail":"Not found"}{"detail":[{"loc":["body","filters","catalogs"],"msg":"Unknown or inactive catalog key","type":"value_error"}]}These examples are synthetic. Framework request-validation errors are limited to 20 entries. Each location has at most eight components; text location components and type are capped at 80 characters and msg at 160. Raw input and validation context are not included by that sanitizer. Service-level validation errors use the same basic field-error shape. Do not assume a stable message identifier or parse English text for application decisions.
| Status | Meaning and frontend response |
|---|---|
| 404 | Missing/ineligible property, invalid public identifier, disabled capability or unavailable/unapproved image. Offer a safe unavailable state; do not reveal or recover private data. |
| 413 | Search body exceeds the configured byte limit; the source default is 65,536 bytes, including streamed bodies. Simplify the request. |
| 422 | Invalid geometry, filter, pagination, query or UUID; unknown/inactive catalog; or requested detail operation unavailable for that listing. Show relevant field guidance and correct the request. |
| 429 | Rate limit exceeded. Respect Retry-After and avoid immediate retries. |
| 500 | Unexpected server failure. The application exception boundary returns {"detail":"Internal Server Error"} and may omit cache headers. Show a generic error and a bounded retry action. |
| 503 | Temporary search/detail/reference/media or admission dependency failure. Show a retry action with bounded backoff. |
Successful public data/media responses and errors handled within the public request boundary use Cache-Control: no-store. The outer application exception boundary returns a generic JSON detail for unexpected 500 errors but may omit that header; this is a current limitation, not a cache permission. As defensive client behavior, also tolerate an unreadable or non-JSON failure from infrastructure without displaying raw response text. Do not persist failed responses or old listings/images in a service worker/CDN cache. Read Publication and privacy.
Pagination contract
Search requests accept page (integer, minimum 1), page_size (integer, minimum 1) and sort. The source defaults are page 1 and page size 24. The public schema caps page_size at 100, and deployment settings may impose a lower maximum. The configured default maximum offset is 10,000:
offset = (page - 1) * page_sizeAn offset above that configured maximum returns 422. sort only accepts PUBLIC_ID_ASC; the implementation orders by numeric property reference and a deterministic tie-breaker. Do not promise lexical sorting by the public identifier's letter prefix.
{"items":[],"total":0,"page":1,"page_size":24,"total_pages":0}This synthetic empty result is a valid 200 response. A late page can have empty items while total and total_pages remain nonzero. Total and page items are selected in one statement snapshot, but separate page requests are not a fixed multi-request snapshot: publications can change between them.
Reset to page 1 after changing filters or geometry. Distinguish initial loading, an empty successful result, invalid input and service failure. Cancel or ignore obsolete search requests so stale results do not replace the newest selection.
Related operations
Pagination applies to POST /api/v1/public/properties/search. Error handling applies to all five reviewed operations, including both image endpoints. See Search and map privacy for filter details.
Updated 1 day ago