MLS Search Errors — A Complete Index

Every error /v3/MLSSearch can return, organized by category. Each error includes an errorCode you can branch on programmatically, plus a human-readable message. As of this write-up, every 400-class error also echoes your original input in the response body so you can correlate the error against exactly what you sent.

How to read an error response

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "...",
  "input": { "...": "your original request payload" },
  "errorCode": "SOME_ERROR_CODE"
}

Some errors attach additional structured fields beyond message — e.g. a list of valid values, or nearby suggestions — always documented per error below.

1. Authentication & Plan Errors

These fire before your filters are even evaluated.

Fix: check your plan status in the billing console, or confirm the correct key/scope is in use.

2. Request Shape Errors (Joi Validation)

Fired when the payload itself is malformed — bad types, unknown fields, missing dependencies. All validation errors are returned together in one response (not one-at-a-time), so fix everything the message lists in a single pass.

Unknown field:

{ "has_ho": true }

→ "has_ho" is not allowed (did you mean "has_hoa"?) — up to 3 ranked suggestions are shown when the name is ambiguous.

Missing required dependency:

{ "mls_number": "382938" }

→ mls_number requires mls_board_code or mls_board_name — MLS numbers are not unique across boards.

Wrong type / shape: standard Joi messages (e.g. "bedrooms" must be a number).

3. Catalog & Enum Value Errors

Fields backed by a fixed vocabulary (property types, feature values, statuses) validate the value against the real catalog. Casing never blocks a match — "duplex" silently resolves to "Duplex". Only a genuinely unrecognized value errors, and it always comes with a suggestion.

Fix: use the suggested value, or check the full catalog listed in the error.

4. Name Field Validation

*_agent_name fields (listing_agent_name, selling_agent_name, colisting_agent_name, coselling_agent_name) require a first and last name — a single token like "Arlene" matches thousands of unrelated agents and is rejected outright rather than silently returning noisy results:

{ "listing_agent_name": "Arlene" }

→ agent name must include at least a first and last name (e.g. "John Smith")

Office name fields (listing_office_name, etc.) don't have this restriction — single-word office names ("Compass", "Redfin") are valid.

5. Cross-Role Field Mismatch (WRONG_ROLE)

If a search on an email, phone, or name field returns zero results, we check whether that exact value exists under a different role before giving up silently — e.g. you searched listing_agent_email but the address is actually under selling_agent_email.

{ "listing_agent_email": "[email protected]" }

→ 400 WRONG_ROLE: listing_agent_email "[email protected]" returned no results — this value exists under: selling_agent_email. Try searching with that field instead.

This covers all 8 roles (listing/selling/colisting/coselling × agent/office) across email, phone, name, and MLS code fields. If zero results are genuinely due to no match anywhere, you instead get the generic zero-results warning (see §11).

6. Ambiguous Identity — a Warning, Not an Error

Not a hard failure — searching a name or MLS code that resolves to more than one real agent/office returns your results plus a structured warning so you can narrow down:

{ "colisting_office_name": "RE/MAX Gold" }

→ 200 response, with:

"warnings": [{
  "warning": "AMBIGUOUS_IDENTITY",
  "field": "colisting_office_name",
  "value": "RE/MAX Gold",
  "totalMatches": 43,
  "message": "colisting_office_name \"RE/MAX Gold\" matches 43 distinct offices (different people / mls_codes). Provide mls_board_code and/or the office's mls_code to narrow down results for this name — see \"matches\".",
  "matches": [{ "officeName": "...", "mlsBoardCode": "...", "mlsBoardName": "...", "listingCount": 12 }]
}]

Additionally, any *_mls_code field used without mls_board_code gets a standing informational warning — even when there's no duplicate today — since MLS codes aren't guaranteed unique across boards:

listing_agent_mls_code is not guaranteed to be unique across MLS boards — include mls_board_code to ensure you target the right listing.

Fix: add mls_board_code to pin the exact board.

7. MLS Board & MLS Number Errors

Fix: use a code from validBoards/boards for mls_board_code, or the name for mls_board_name.

8. School District Errors

school_district matches against real district names in full — never by a single word, so a bare "Houston" won't silently return every "Houston"-adjacent district.

{ "school_district": "Dallas" }

→ No school district closely matches "Dallas" — did you mean one of: "Dallas ISD", "211 - Dallas", ...? District names are matched in full, not by individual words.

9. Geo & Radius Errors

10. Range & Sort Errors

11. Unsupported Filters & Silent Zero-Results

Unsupported filter (UNSUPPORTED_FILTER, 400): some v2-parity field names have no v3 target — these fail loudly with an actionable hint rather than silently ignoring the filter:

{ "county": "Travis" }

→ Unsupported v3 MLS filter(s): county (county is public-record sourced — use public_county)

Other examples: sold_price/sold_date_* (not yet indexed on the MLS side — use public-record fields), listing_office_address/selling_office_address (not searchable — use _name/_mls_code), pets_allowed/has_spa_features/spa_features (pending pipeline population).

Silent zero-results (not an error): a well-formed query that simply matches nothing returns 200 with recordCount: 0 and a plain warning: "Your search returned 0 matches — the filters may be too restrictive." Combined with §5/§6, most silent misses on identity fields now get a more specific explanation instead.

12. Field-Selection Errors

13. Server Errors

Quick Reference: All Error Codes