# Limits & errors

> Every Map API limit with its number, and every error code with its HTTP status, what causes it and what to do, including the daily area limit on pin views.

- **HTML:** https://offendersearch.app/docs/map/limits-and-errors
- **Base URL:** https://api.offendersearch.app
- **Authentication:** `X-API-Key` request header
- **Map API reference as markdown:** https://offendersearch.app/docs/map.md

## Limits

| Limit | Value | What happens at it |
| --- | --- | --- |
| Pins start at zoom | 13 | Below it a view is answered as clusters. |
| Names start at zoom | 15 | Below it a pin has no `label`. |
| Lowest zoom answered | 3 | A wider view is answered at this zoom. |
| `zoom` parameter | 0 to 22 | Outside it: `422 invalid_zoom`. |
| Map tiles in one view | 64 | A wider box is answered at a lower zoom. It is not refused. |
| Pins in one response | 300 | A denser view is answered as clusters on a finer grid. |
| People inline on a many-people pin | 10 | Past it, use the groups route. |
| Group page size | 1 to 100, default 50 | Outside it: `422 invalid_page`. |
| Marker id and group id life | 24 hours | `410 marker_expired` or `410 group_expired`. |
| Free re-open by `recordRef` | 24 hours | After it, opening by reference is one record open again. |
| Signed photo link | 1 hour | Open the record again for a new link. |
| Radius | 0.1 to 100 miles | Outside it: `422 invalid_radius`. |
| Polygon points | 3 to 200 | Outside it: `422 invalid_shape`. |
| Route points | 2 to 200 | Outside it: `422 invalid_shape`. |
| Route buffer | 0.05 to 5 miles | Outside it: `422 invalid_shape`. |
| Browser cache time | 300 seconds | The `max-age` on a view. |
| Longest life of an `ETag` | 12 hours | After it the same view is a new answer with new ids. |
| Distinct areas read for pins, for each account, each day | 20,000 | `429 map_sweep_limit`. See below. |
| The same, for each end user (`X-End-User`) | 2,000 | `429 map_end_user_limit`. |
| Map requests answered at the same moment | 2 on each API server | `429 map_busy` with `Retry-After: 1`. |

Your account’s own values for the zoom thresholds, the pin cap and the area limits are in `GET /v1/map/status`.

## The daily area limit

Pins are counted by area. The map is divided into fixed squares, the map tiles of zoom 14. Each day an account may read pins for 20,000 different squares.

- **Only different squares count.** Looking at the same neighbourhood a thousand times in a day counts its squares once.
- **Only pins count.** Cluster views are never limited, and they keep working after the limit is reached. Test mode is never counted.
- **It resets each day**, at midnight UTC.
- **Each end user has a share.** When you send `X-End-User`, that person may read pins for 2,000 different squares a day. One person paging across a whole state is then stopped with `map_end_user_limit` before the account’s limit is touched.
- **Normal use does not reach it.** People browsing a map look at a small number of places. The limit stops a copy of every pin in the country being taken through the map.

To have either number raised, write to support@offendersearch.app with your account, what the map is for and the number you need. Both are set for each account.

## The error body

Every error has the same shape. Switch on `detail.code`. Show `detail.message` to a developer, not to an end user.

403 Forbidden

```json
{
  "detail": {
    "code": "map_not_enabled",
    "message": "The Map API is not turned on for this account. …",
    "dashboardUrl": "https://offendersearch.app/dashboard/map-api",
    "docsUrl": "https://offendersearch.app/docs/map/turn-it-on"
  }
}
```

Some errors add `dashboardUrl`, `docsUrl`, `billingUrl` or `retryAfterSeconds`. No error response is billed.

## Request errors

| Code | Status | Cause | What to do |
| --- | --- | --- | --- |
| `invalid_bbox` | 422 | `bbox` is missing or is not `west,south,east,north`, or it was sent together with `center`. | Send four numbers in degrees: south below north, west and east within ±180 and different. Send `bbox` or `center`, not both. |
| `invalid_center` | 422 | `center` is not `lat,lng`, or it came without `radiusMiles`. | Send `center=lat,lng` together with `radiusMiles`. |
| `invalid_radius` | 422 | `radiusMiles` is not a number from 0.1 to 100. | Send a radius inside the range. |
| `invalid_zoom` | 422 | `zoom` is not a number from 0 to 22. | Send the map’s zoom, or leave it out. |
| `invalid_filter` | 422 | `housing` or `precision` has a value that is not listed. | Use `housed`, `homeless`, `incarcerated` for `housing`, and `street` or `any` for `precision`. |
| `invalid_format` | 422 | `format` is not `json` or `geojson`. | Send one of the two. |
| `invalid_detail` | 422 | `detail` is not `full` or `count`. | Send one of the two. |
| `invalid_page` | 422 | `page` is below 1, or `perPage` is not 1 to 100. | Send a page from 1 and a page size inside the range. |
| `invalid_shape` | 422 | The body has both or neither of `polygon` and `route`, the wrong number of points, or a buffer outside the range. | Send one shape, inside the limits above. |

## Access errors

| Code | Status | Cause | What to do |
| --- | --- | --- | --- |
| — | 401 | The key is missing or wrong, or a map browser key was used on a route that does not accept one. | Send a valid key in `X-API-Key`. Use a secret key, from your server, for other routes. |
| `map_not_enabled` | 403 | The Map API is off for this account. | Turn it on. See [Turn it on](https://offendersearch.app/docs/map/turn-it-on.md). To build first, send `sandbox=true`. |
| `map_paused` | 403 | We have paused the Map API for this account. | Write to support@offendersearch.app. |
| `origin_not_allowed` | 403 | A map browser key was used from a site that is not on its list. | Add the site to the key, or call from your server with a secret key. See [Access & keys](https://offendersearch.app/docs/map/access.md). |

## Id errors

| Code | Status | Cause | What to do |
| --- | --- | --- | --- |
| `unknown_marker` | 404 | The marker id or reference is not one this account was given. | Use ids from your own responses, with a key of the same account. |
| `unknown_group` | 404 | The group id is not one this account was given. | The same. |
| `marker_expired` | 410 | The marker id is older than 24 hours. | Request the view again for a new id. For saved links, keep the `recordRef`. |
| `group_expired` | 410 | The group id is older than 24 hours. | Request the view again for a new id. |
| `record_no_longer_listed` | 410 | The registry no longer lists the person. Not billed. | Remove the pin, and say the record is no longer listed. |

## Limit errors

| Code | Status | Cause | What to do |
| --- | --- | --- | --- |
| `map_sweep_limit` | 429 | The account has used its area limit for the day. | Clusters still work: show them and ask the user to try pins tomorrow. If normal use reaches it, ask us to raise it. |
| `map_end_user_limit` | 429 | One end user has used their area limit for the day. | Tell that user. Other users are not affected. |
| `map_busy` | 429 | Too many map requests at the same moment. | Retry after the `Retry-After` header, which is 1 second. Wait for the map to settle and cancel requests you no longer need. |
| `overloaded` | 429 | The service is at capacity. | Retry after the `Retry-After` header. |

A `429` here is not a charge and not a ban. Wait for the time in `Retry-After` and send the request again.

## Service errors

| Code | Status | Cause | What to do |
| --- | --- | --- | --- |
| `map_index_not_ready` | 503 | The map data is not ready to answer yet. | Retry shortly. |
| `map_unavailable` | 503 | The map could not be read just now. Nothing was charged. | Retry after the `Retry-After` header. |
| `map_not_configured` | 503 | The Map API is not available on this server. | Retry. If it continues, write to us. |

## Turn-on errors

These come only from `POST /v1/map/enable` and `POST /v1/map/disable`.

| Code | Status | Cause | What to do |
| --- | --- | --- | --- |
| `minimum_not_accepted` | 422 | `acceptMinimum` was not `true`. | Send `{"acceptMinimum": true}`. |
| `payment_method_required` | 402 | There is no card on the account, or it is on the free trial. | Add a payment method in the dashboard under Billing, then try again. |
| `payment_failed` | 402 | The card was declined. Nothing was turned on and nothing was charged. | Fix or replace the card, then try again. |
| `business_account_required` | 403 | The account is a personal account. | Use a business account. |
| `admin_required` | 403 | The dashboard seat is not an admin of the account. | Ask an account admin to turn it on, or use a secret key. |

---

## Related

- Previous: [Billing](https://offendersearch.app/docs/map/billing.md)
- Index: [Map API reference](https://offendersearch.app/docs/map.md)