Troubleshooting MLS Board Utility Errors

MLS Board Utility Errors: A Complete Index

Every error /v3/MLSBoardCoverage can return, organized by category. This is a reference lookup (which boards exist, and which boards cover each zip, county or city), not a listing search. Each call counts as one unit of usage, no matter how many rows come back.

Tag scheme

Every error type below is tagged three ways:

• Tag: a short human-readable label (e.g. Too Many States).
• 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. All validation problems come back at once. If your request has several mistakes, the message lists every one, joined by periods, so you can fix them in a single pass.
2. state is required in every mode. Send one 2-letter code or an array of up to 5. CA, TX and FL are very large and must each be requested on their own. Lowercase codes are accepted.
3. Empty results are not an error. A state with no covered boards returns 200 with "data": [] and "recordCount": 0.
4. Pagination uses a cursor, not page numbers. In zips, counties and cities modes, pass the next_cursor from the previous response, exactly as returned, to get the next page. next_cursor is null on the last page. mode: "boards" always returns the full list in one response, and size and cursor are ignored there.

How to read an error response

Validation errors (400) use this shape:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "\"mode\" must be one of [boards, zips, counties, cities]. `state` must be a 2-letter code, an array of them, or \"ALL_STATES\".",
  "validation": { "source": "payload", "keys": ["mode", "state"] }
}

Errors with a structured code add errorCode (and, for cursor errors, echo your input):

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid cursor — pass the `next_cursor` value from a previous response verbatim.",
  "input": { "mode": "zips", "state": "AZ", "cursor": "not-a-cursor", "size": 500 },
  "errorCode": "INVALID_CURSOR"
}

Where errors come from

1. Request Shape Errors (Validation)

Missing Mode (400)

{ "state": "TX" }

Returns: "mode" is required

Invalid Mode (400)

mode must be boards, zips, counties or cities.

{ "mode": "states", "state": "TX" }

Returns: "mode" must be one of [boards, zips, counties, cities]

Missing State (400)

{ "mode": "boards" }

Returns: "state" is required

Invalid State (400)

state must be a 2-letter code, an array of codes, or "ALL_STATES". Full names and numbers are rejected.

{ "mode": "boards", "state": "Texas" }

Returns: `state` must be a 2-letter code, an array of them, or "ALL_STATES".

Empty State List (400)

{ "mode": "boards", "state": [] }

Returns: `state` array must contain at least one 2-letter code.

Invalid State Entry (400)

{ "mode": "boards", "state": ["AZ", "1Z"] }

Returns: Each entry in `state` must be a 2-letter state code.

Duplicate States (400)

{ "mode": "boards", "state": ["AZ", "AZ"] }

Returns: `state` array must not contain duplicate codes.

Large State Batched (400)

CA, TX and FL must each be requested alone.

{ "mode": "boards", "state": ["TX", "OK"] }

Returns: TX must be requested one state per call (these states are very large) — send a separate request for each. Up to 5 states can otherwise be combined in one request.

Too Many States (400)

{ "mode": "boards", "state": ["AZ", "NV", "UT", "CO", "NM", "OR"] }

Returns: A maximum of 5 states can be requested per call (except CA, TX, FL, which must each be requested on their own) — please break up your requests.

Invalid Size (400)

size (page size for zips / counties / cities) must be a whole number from 1 to 2000. The default is 500.

{ "mode": "zips", "state": "AZ", "size": 2001 }

Returns: "size" must be less than or equal to 2000 (also "size" must be greater than or equal to 1 and "size" must be an integer)

Invalid Cursor: INVALID_CURSOR (400)

The cursor could not be read. Pass next_cursor from the previous response exactly as returned, and never edit or build it yourself.

{ "mode": "zips", "state": "AZ", "cursor": "not-a-cursor" }

Returns: Invalid cursor — pass the `next_cursor` value from a previous response verbatim.

Invalid Type (400)

cursor must be a string; group_by_state and show_all must be true or false.

{ "mode": "boards", "state": "AZ", "group_by_state": "yes" }

Returns: "group_by_state" must be a boolean

Unknown Field (400)

Only mode, state, group_by_state, show_all, size and cursor are accepted. Check spelling.

{ "mode": "boards", "state": "AZ", "states": "AZ" }

Returns: "states" is not allowed

Missing API Key (400)

Returns: "x-api-key" is required

2. Authentication & Plan Errors

National MLS Required applies to "state": "ALL_STATES", which removes the state scope and returns every board nationwide. It is reserved for National MLS customers; other keys should request specific states.

Returns: "ALL_STATES" is available to National MLS customers only. Request specific state(s) with `state`, or contact us about National MLS access.

3. Usage & Billing Errors

Each call counts as one unit of MLS usage, so the standard usage checks apply.

Fix: check your plan and balance in the billing console. Pay-as-you-go accounts need the MLS add-on to use MLS endpoints.

4. Test Keys (warning, not an error)

Requests made with a test key succeed but include:

{ "live": false, "warning": "Your key is in test mode. Restrictions will apply until you go live." }

5. Server Errors

No internal detail is included. A requestId is returned when available; include it when contacting support. A cursor that was edited or built by hand can also end up here instead of returning INVALID_CURSOR, which is one more reason to pass next_cursor through untouched.

Quick Reference: All Errors by Status