MLS Property Mapping (Pins) Errors
POST /v3/MLSPropertyMapping returns minimal { id, latitude, longitude } map points for matching listings. It is a thin wrapper over /v3/MLSSearch — it accepts the exact same request schema (every filter, exclude, and/or, geo, etc.) and internally sets mapping_only, then returns only the coordinate points instead of full records.
Shared errors: because the query surface is MLS Search, all filter-validation, catalog/enum, geo, board, identity, cross-role, and auth/plan errors behave identically to MLS Search. See MLS Search Errors — A Complete Index for the full catalog. This page covers only what is specific to the mapping endpoint.
Tag scheme
Each error has a human-readable Tag, a machine Error Code, and an HTTP status. ✅ = emitted today · 🟨 = proposed.
1. Page Size — the One Thing That Differs from MLS Search
The mapping endpoint exists to feed maps, where each record is tiny (an id + two coordinates), so it allows a much larger page than MLS Search.
| Endpoint | Default size | Max size |
|---|---|---|
| MLS Search (full records, count, ids_only, listing_ids_only) | 50 | 250 |
| MLS Property Mapping (pins) | 50 | 10,000 |
| MLS Detail Bulk | — | 1,000 (array length) |
- Omitting
sizereturns the default 50 points. sizeabove the endpoint max is clamped down to the max — it is not rejected. Requestingsize: 25000on pins returns 10,000 points (the cap), not a 400.resultIndexpages through results; note Elasticsearch's result window meansresultIndex + sizeshould stay within 10,000 for a single deep page.
There is no error code for exceeding the page size — the clamp is silent by design. If you need to know you hit the ceiling, compare data.length against your requested size.
2. Everything Else — Inherited from MLS Search
Because pins delegates to the MLS Search query layer, these all apply unchanged (see the MLS Search errors index for details and examples):
| Category | Examples |
|---|---|
| Filter validation | unknown field, catalog/enum value errors, name-field rules |
| Geo / radius | CONFLICTING_GEO, INCOMPLETE_GEO, ANCHOR_NOT_FOUND, USE_MLS_DETAIL |
| Board / mls_number | INVALID_BOARD_CODE, MLS_NUMBER_NEEDS_BOARD |
| Range / sort | INVALID_RANGE, INVALID_SORT_FIELD |
| Unsupported filters | UNSUPPORTED_FILTER |
| Identity / cross-role | AMBIGUOUS_IDENTITY (warning), WRONG_ROLE, SCHOOL_DISTRICT_NOT_FOUND |
| Auth / plan | AUTH_SCOPE_UNAUTHORIZED, MLS_PLAN_REQUIRED, MLS_SUBSCRIPTION_INACTIVE, WALLET_INSUFFICIENT_BALANCE, rate/usage 429s |
| Server | INTERNAL_ERROR (500) |
3. Response Shape Note (not an error)
A well-formed query that matches nothing returns 200 with data: [] and recordCount: 0 — same as MLS Search. Coordinates can be null on a matched listing that has no geocode; those points are still returned (with latitude/longitude null) rather than dropped.
Quick Reference
| HTTP | Pins-specific behavior |
|---|---|
| 200 | Normal result; size > 10,000 was clamped to 10,000 (silent, no error) |
| (all other errors) | Identical to MLS Search — pins adds no new error codes beyond the page-size behavior above |