MLS Detail Bulk Errors

POST /v3/MLSDetailBulk retrieves many v3 MLS records at once. It shares the record shape, fields/field_sections selection, public opt-in, and per-record resolution logic with /v3/MLSDetail.

Shared errors: authentication, plan/scope gating, public-record omission, field-selection errors, and server errors behave identically to the single-record endpoint. See MLS Detail Errors — A Complete Index for those. This page covers only what is specific to the bulk endpoint.

Tag scheme

Same as the Detail page: each error has a human-readable Tag, a machine Error Code, and an HTTP status. ✅ = emitted today · 🟨 = proposed (returns the correct HTTP status now; structured errorCode not yet emitted).

1. Input Shape — the Bulk-Specific Rules

A bulk request must carry exactly one of listing_ids or assessor_ids, each an array of 1–1000 IDs.

Missing ID Array — MISSING_ID_ARRAY (400)

Neither array was supplied (.xor('listing_ids', 'assessor_ids')).

{ "fields": ["listingPrice"] }

→ "value" must contain at least one of [listing_ids, assessor_ids]

Both ID Arrays Provided — CONFLICTING_ID_ARRAYS (400)

listing_ids and assessor_ids are mutually exclusive — send one, not both.

{ "listing_ids": [123], "assessor_ids": [456] }

→ "value" contains a conflict between exclusive peers [listing_ids, assessor_ids]

Too Many IDs — TOO_MANY_IDS (400)

Each array is capped at 1000 entries. A 1001-element array is rejected outright (not truncated).

{ "listing_ids": [ /* 1001 ids */ ] }

→ "listing_ids" must contain less than or equal to 1000 items

Empty ID Array — EMPTY_ID_ARRAY (400)

An array must contain at least 1 entry.

{ "assessor_ids": [] }

→ "assessor_ids" must contain at least 1 items

Invalid ID Type — VALIDATION_FAILED (400)

listing_ids items must be numbers. assessor_ids items must be numbers (or null — see §2).

{ "listing_ids": ["abc"] }

→ "listing_ids[0]" must be a number

2. Per-Position Results — Misses Are Not Errors

The response is order-preserving: data[] lines up 1:1 with the requested ID array. A missing record or a null entry does not fail the request — it becomes an error object at that position so the array stays aligned.

Error object shape:

{ "id": 999999, "match": false, "error": true, "errorMessage": "No listing found for this listing ID." }

recordCount counts only real matches — error objects are excluded, and billing is based on recordCount.

3. All-Miss Response (404)

If every requested ID misses (zero real matches), the endpoint returns 404 — but data[] still contains one error object per requested position so you can see which IDs failed.

If even one ID matches, the response is 200 with a mix of records and error objects.

Quick Reference