Troubleshooting MLS AutoComplete Errors

MLS AutoComplete Errors: A Complete Index

Every error /v3/MLSAutoComplete can return, organized by category. MLS AutoComplete is free for any key with an active MLS plan (it is not metered), so the usage and wallet errors other MLS endpoints return never apply here.

Tag scheme

Every error type below is tagged three ways:

• Tag: a short human-readable label (e.g. Search Too Short).
• Error Code: the machine string returned in errorCode, when the API returns one.
• HTTP: the exact status code.

Status legend: ✅ = structured errorCode returned today · — = the correct HTTP status is returned, but there is no errorCode yet (read the message instead).

Four behaviors to know first

1. Validation stops at the first problem. If your request has two mistakes, the API reports only the first one. Fix it and resend, since there may be another.
2. No matches is not an HTTP error. A search that finds nothing returns HTTP 200 with "statusCode": 404 and "statusMessage": "Not Found" in the body, and an empty data array. Check data.length (or the body's statusCode), not just the HTTP status.
3. Results can be partial. Addresses, streets and MLS boards come from MLS data, while cities, counties, zips and states come from a separate place index. If you request types from both and one source is briefly unavailable, you still get a 200 with results from the source that answered.
4. Location biasing only affects addresses. latitude and longitude boost nearby results for search_types A (address) only. They have no effect on other types.

How to read an error response

Validation errors (400) use this shape:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "\"search\" is required",
  "validation": { "source": "payload", "keys": ["search"] }
}

Authentication and plan errors add an errorCode:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Key not found for key provided. Please go to RealEstateAPI.com to register for an active API Key.",
  "errorCode": "AUTH_KEY_NOT_FOUND"
}

Where errors come from

1. Request Shape Errors (Validation)

Missing Search (400)

search is required.

{ "search_types": "A" }

Returns: "search" is required

Search Too Short (400)

search needs at least 2 characters.

{ "search": "a" }

Returns: "search" length must be at least 2 characters long

Invalid Type (400)

Each field must be the right type: search is a string, latitude/longitude/precision are numbers.

{ "search": 123 }

Returns: "search" must be a string

Invalid Search Type (400)

search_types accepts one code or an array of codes: A Address, S Street, C City, N County, Z Zip, B MLS Board, T State. It defaults to A when omitted.

The message names an internal label rather than search_types. Both versions below mean the search_types value is not valid.

{ "search": "123 Main", "search_types": "X" }

Returns: "MLSAutoCompleteSearchTypeList" must be one of [T, Z, N, C, B, S, A, array]

{ "search": "123 Main", "search_types": ["A", "Q"] }

Returns: "MLSAutoCompleteSearchTypeEnums" must be one of [T, Z, N, C, B, S, A]

Incomplete Coordinates (400)

latitude and longitude must be sent together.

{ "search": "123 Main", "latitude": 30.27 }

Returns: "MLSAutoCompleteRequest" contains [latitude] without its required peers [longitude]

Coordinate Out of Range (400)

latitude must be between -90 and 90; longitude between -180 and 180.

{ "search": "123 Main", "latitude": 95, "longitude": -97 }

Returns: "latitude" must be less than or equal to 90

Invalid Precision (400)

precision must be a whole number from 1 to 10.

{ "search": "123 Main", "latitude": 30.27, "longitude": -97.74, "precision": 11 }

Returns: "precision" must be less than or equal to 10 (or "precision" must be an integer for values like 2.5)

Unknown Field (400)

Only search, search_types, latitude, longitude and precision are accepted. Check spelling.

{ "search": "123 Main", "serch_types": "A" }

Returns: "serch_types" is not allowed

Missing API Key (400)

Requests without the x-api-key header are rejected before anything else.

Returns: "x-api-key" is required

2. Authentication & Plan Errors

These fire before the search runs.

• Domain Not Allowed applies when your key is restricted to specific domains and the request comes from a browser page on another domain. This is common with type-ahead widgets: add the site's domain to the key's allowed domains.
• Scope Unauthorized means the key has no MLS access at all. Any MLS scope is enough for AutoComplete.
• MLS Plan Required / MLS Subscription Inactive: AutoComplete needs an active MLS subscription or the MLS add-on. Check your plan in the billing console.

3. No Matches (200, not an error)

A valid search that finds nothing:

{
  "input": { "search": "zzqxvbnmzzqx", "search_types": "A" },
  "data": [],
  "totalResults": 0,
  "returnedResults": 0,
  "statusCode": 404,
  "statusMessage": "Not Found"
}

The HTTP status is 200. Try fewer characters, a different search_types, or confirm the area is covered by your MLS boards.

4. Search Unavailable

Returns: MLS AutoComplete is not available.

This means the search index needed for your search_types could not be reached. Retry after a short wait. If you requested types from both sources and only one is down, you get partial results instead of a 503 (see "Four behaviors to know first").

5. Server Errors

No internal detail is included. A requestId is returned when available; include it when contacting support.

Quick Reference: All Errors by Status