---
updatedAt: 2026-10-02T19:50:17.000Z
agentTools:
  projectIndex: https://developer.realestateapi.com/llms.txt
---

# Troubleshooting MLS Board Utility Errors

Every error /v3/MLSBoardCoverage can return, with example requests and the exact messages.

## 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`**&#x20;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:

```json
{
  "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`):

```json
{
  "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

| Layer                         | Trigger                                               | Becomes                   |
| ----------------------------- | ----------------------------------------------------- | ------------------------- |
| Request validation            | missing or malformed field, unknown field             | 400, all problems at once |
| Key, usage and billing checks | bad key, usage limits, wallet balance                 | 401 / 402 / 403 / 429     |
| Plan check                    | no MLS plan, `ALL_STATES` without National MLS access | 402 / 403                 |
| Lookup                        | bad cursor                                            | 400 `INVALID_CURSOR`      |
| Uncaught                      | anything else                                         | 500 `INTERNAL_ERROR`      |

## 1. Request Shape Errors (Validation)

| Tag                 | Error Code       | HTTP | Status |
| ------------------- | ---------------- | ---- | ------ |
| Missing Mode        | —                | 400  | —      |
| Invalid Mode        | —                | 400  | —      |
| Missing State       | —                | 400  | —      |
| Invalid State       | —                | 400  | —      |
| Empty State List    | —                | 400  | —      |
| Invalid State Entry | —                | 400  | —      |
| Duplicate States    | —                | 400  | —      |
| Large State Batched | —                | 400  | —      |
| Too Many States     | —                | 400  | —      |
| Invalid Size        | —                | 400  | —      |
| Invalid Cursor      | `INVALID_CURSOR` | 400  | ✅      |
| Invalid Type        | —                | 400  | —      |
| Unknown Field       | —                | 400  | —      |
| Missing API Key     | —                | 400  | —      |

### Missing Mode (400)

```json
{ "state": "TX" }
```

Returns: `"mode" is required`

### Invalid Mode (400)

`mode` must be `boards`, `zips`, `counties` or `cities`.

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

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

### Missing State (400)

```json
{ "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.

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

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

### Empty State List (400)

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

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

### Invalid State Entry (400)

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

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

### Duplicate States (400)

```json
{ "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.

```json
{ "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)

```json
{ "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.

```json
{ "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.

```json
{ "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`.

```json
{ "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.

```json
{ "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

| Tag                       | Error Code                  | HTTP | Status |
| ------------------------- | --------------------------- | ---- | ------ |
| Key Not Found             | `AUTH_KEY_NOT_FOUND`        | 401  | ✅      |
| Key Inactive              | `AUTH_KEY_INACTIVE`         | 401  | ✅      |
| Test Key Expired          | —                           | 401  | —      |
| Domain Not Allowed        | `AUTH_DOMAIN_NOT_ALLOWED`   | 403  | ✅      |
| Scope Unauthorized        | `AUTH_SCOPE_UNAUTHORIZED`   | 403  | ✅      |
| MLS Plan Required         | `MLS_PLAN_REQUIRED`         | 403  | ✅      |
| MLS Subscription Inactive | `MLS_SUBSCRIPTION_INACTIVE` | 402  | ✅      |
| National MLS Required     | `NATIONAL_MLS_REQUIRED`     | 403  | ✅      |

**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.

| Tag                            | Error Code                      | HTTP | Status |
| ------------------------------ | ------------------------------- | ---- | ------ |
| Insufficient Balance           | `WALLET_INSUFFICIENT_BALANCE`   | 402  | ✅      |
| Not Available on Pay-As-You-Go | `WALLET_ENDPOINT_NOT_AVAILABLE` | 403  | ✅      |
| Daily Cap Reached              | `DAILY_USAGE_EXCEEDED`          | 429  | ✅      |
| Monthly Cap Reached            | `MONTHLY_USAGE_EXCEEDED`        | 429  | ✅      |
| Test Key Cap Reached           | —                               | 429  | —      |

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:

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

## 5. Server Errors

| Tag            | Error Code       | HTTP | Status |
| -------------- | ---------------- | ---- | ------ |
| Internal Error | `INTERNAL_ERROR` | 500  | ✅      |

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

| HTTP | Tag (Error Code)                                                                                                                                                                                                                                                    |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | Missing Mode · Invalid Mode · Missing State · Invalid State · Empty State List · Invalid State Entry · Duplicate States · Large State Batched · Too Many States · Invalid Size · Invalid Cursor (`INVALID_CURSOR`) · Invalid Type · Unknown Field · Missing API Key |
| 401  | Key Not Found (`AUTH_KEY_NOT_FOUND`) · Key Inactive (`AUTH_KEY_INACTIVE`) · Test Key Expired                                                                                                                                                                        |
| 402  | MLS Subscription Inactive (`MLS_SUBSCRIPTION_INACTIVE`) · Insufficient Balance (`WALLET_INSUFFICIENT_BALANCE`)                                                                                                                                                      |
| 403  | Domain Not Allowed (`AUTH_DOMAIN_NOT_ALLOWED`) · Scope Unauthorized (`AUTH_SCOPE_UNAUTHORIZED`) · MLS Plan Required (`MLS_PLAN_REQUIRED`) · National MLS Required (`NATIONAL_MLS_REQUIRED`) · Not Available on Pay-As-You-Go (`WALLET_ENDPOINT_NOT_AVAILABLE`)      |
| 429  | Daily Cap Reached (`DAILY_USAGE_EXCEEDED`) · Monthly Cap Reached (`MONTHLY_USAGE_EXCEEDED`) · Test Key Cap Reached                                                                                                                                                  |
| 500  | Internal Error (`INTERNAL_ERROR`)                                                                                                                                                                                                                                   |