# Routing coverage and errors

> Where geolith routing answers (10 cities, the coverage GeoJSON at api.geolith.app/v1/routing/coverage, any API key) and every routing error: 1001 outside coverage, 1002 different cities, 1004 read limit, key, quota and rate errors, with example bodies.

Routing is available in 10 cities. Planet coverage comes later. Every location of one request must be inside one city.

## The cities

Each city covers its continuous built-up area plus 15 km on every side, rounded out to 0.05°.

| City                   | Country | Id              |
| ---------------------- | ------- | --------------- |
| Bengaluru              | IN      | `bengaluru`     |
| Mumbai                 | IN      | `mumbai`        |
| Delhi                  | IN      | `delhi`         |
| London                 | GB      | `london`        |
| Berlin                 | DE      | `berlin`        |
| Paris                  | FR      | `paris`         |
| New York               | US      | `new-york`      |
| San Francisco Bay Area | US      | `san-francisco` |
| Singapore              | SG      | `singapore`     |
| Tokyo                  | JP      | `tokyo`         |

The bounds of each city, by id, as `[west, south, east, north]` in degrees:

```json
{
  "bengaluru": [77.25, 12.65, 78.0, 13.35],
  "mumbai": [72.6, 18.75, 73.4, 19.65],
  "delhi": [76.7, 28.2, 77.7, 29.05],
  "london": [-0.75, 51.15, 0.55, 51.85],
  "berlin": [12.75, 52.15, 14.05, 52.85],
  "paris": [1.75, 48.5, 2.95, 49.2],
  "new-york": [-74.55, 40.3, -73.35, 41.2],
  "san-francisco": [-122.7, 37.05, -121.6, 38.2],
  "singapore": [103.45, 1.15, 104.25, 1.75],
  "tokyo": [139.15, 35.15, 140.3, 36.1]
}
```

- Delhi includes Gurugram, Faridabad, Noida, Greater Noida and Ghaziabad.
- Mumbai includes Thane, Navi Mumbai, Kalyan-Dombivli, Vasai-Virar and Panvel.
- Bengaluru includes Hosur.
- Singapore includes the Johor Bahru built-up area. It has no Indonesian roads.
- The San Francisco Bay Area includes Oakland, Berkeley, Fremont and San Jose.

The coverage GeoJSON is the source of truth. The table can lag behind it.

## The coverage GeoJSON

```bash
curl "https://api.geolith.app/v1/routing/coverage" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

- `GET` only. It needs an API key: a secret key, or a publishable key from one of its allowed origins, so a map in the browser can draw the cities.
- No key or a bad key gets `401`. A publishable key from another origin gets `403 origin_not_allowed`.
- Each city carries its service `limits` ([Limits per city](/routing/limits-and-units#limits-per-city)).
- It costs no routing units and uses no allowance (`X-Routing-Units: 0`). It counts against the key's normal request rate.
- Answers may be kept for 5 minutes (`Cache-Control: private, max-age=300`).
- The answer is a GeoJSON FeatureCollection with one feature per city, sorted by id.

```json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "bengaluru",
      "bbox": [77.25, 12.65, 78, 13.35],
      "properties": {
        "id": "bengaluru",
        "name": "Bengaluru",
        "country": "IN",
        "built": "2026-11-16",
        "limits": {
          "isochrone_minutes": { "auto": 15, "bicycle": 15, "pedestrian": 60 },
          "isochrone_km": { "auto": 1, "bicycle": 1, "pedestrian": 0 },
          "trace_km": 30,
          "matrix_span_km": { "25": 20, "100": 20, "625": 10 }
        }
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [77.25, 12.65],
            [78, 12.65],
            [78, 13.35],
            [77.25, 13.35],
            [77.25, 12.65]
          ]
        ]
      }
    }
  ]
}
```

`built` is the build date of the city's data. The `X-Routing-Build` header of an answer carries the same date. `limits` are the city's service limits, the same as the table in [Limits per city](/routing/limits-and-units#limits-per-city).

**Which city answers.** A request goes to the one city that holds all its locations: route `locations`, matrix `sources` and `targets`, the isochrone location, and every trace point. If two cities hold them all, the smaller city answers. The `X-Routing-City` header names the city.

## Two error shapes

Routing errors come in two shapes.

- **Errors from the router** keep Valhalla's body: `error_code`, `error`, `status_code` and `status`. These are coverage errors and request errors.
- **Errors from api.geolith.app** use the `error` object of every geolith API: `code`, `message` and `docs`. These are key, quota, rate and size errors. See [Quotas and errors](/search/hosted/quotas-and-errors#errors).

No error uses routing units. An error from the router carries `X-Routing-Units: 0`.

## Coverage errors

### 1001: outside coverage

A location is in no city. HTTP 400.

```json
{
  "error_code": 1001,
  "error": "Location is outside routing coverage. Covered cities: Bengaluru, Berlin, Delhi, London, Mumbai, New York, Paris, San Francisco Bay Area, Singapore, Tokyo. See https://docs.geolith.app/routing/coverage-and-errors",
  "status_code": 400,
  "status": "Bad Request"
}
```

Check the location against the coverage GeoJSON. Do not retry the same request.

### 1002: locations in different cities

Every location is in a city, but no one city holds them all. HTTP 400. Routes between cities are not served yet.

```json
{
  "error_code": 1002,
  "error": "Locations are in different cities (Berlin, Paris): routing between cities is not served yet. See https://docs.geolith.app/routing/coverage-and-errors",
  "status_code": 400,
  "status": "Bad Request"
}
```

Split the request so that each part stays in one city.

### 1004: too heavy for one request

HTTP 400. A request gets 1004 when it would pass one of three limits: it needs more than 64 MiB of map data, it needs more memory than one request may use, or it would take too long. Long walking routes that use a ferry can do this, and so can a few requests with no possible route. Car routes inside a city were not refused in testing. A 1004 answer uses no routing units. The answer does not say which limit was reached: the body is the same for all three.

```json
{
  "error_code": 1004,
  "error": "This request needs more map data than one request may read (for example a long walking route that uses a ferry). Shorten the route or split it.",
  "status_code": 400,
  "status": "Bad Request"
}
```

Shorten the route or split it into legs.

## Over a city's limits

Each city has service limits: isochrone time and distance, trace length and matrix span. See [Limits per city](/routing/limits-and-units#limits-per-city). A request over a limit is refused at once, before any map data is read. The answer is HTTP 400 with Valhalla's own limit error. It uses no routing units.

| Code  | When, and the message                                                                                                                               |
| ----- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `150` | A matrix over 625 cells. `Exceeded max locations: 625.000000`                                                                                       |
| `151` | An isochrone time over the city's limit for its costing. `Exceeded max time: <minutes>`                                                             |
| `152` | More than 4 isochrone contours. `Exceeded max contours: 4`                                                                                          |
| `153` | A trace with more than 16,000 points. `Too many shape points: (<n>). The limit is 16000`                                                            |
| `154` | A trace longer than the city's limit, or a matrix pair farther apart than its span. `Path distance exceeds the max distance limit: <metres> meters` |
| `166` | An isochrone distance over the city's limit; 0 means no distance contours. `Exceeded max distance: <km>`                                            |

A car isochrone of 10 minutes in Paris (limit 2 minutes):

```json
{
  "error_code": 151,
  "error": "Exceeded max time: 2",
  "status_code": 400,
  "status": "Bad Request"
}
```

A trace of 3 km in Paris (limit 2 km):

```json
{
  "error_code": 154,
  "error": "Path distance exceeds the max distance limit: 2000 meters",
  "status_code": 400,
  "status": "Bad Request"
}
```

Make the request smaller, or split it. Do not retry it as is.

## Request errors from the router

Every other router error is Valhalla's own code and message, with HTTP 400. Common ones:

| Code  | When                                                        |
| ----- | ----------------------------------------------------------- |
| `171` | No road near a location (`No suitable edges near location`) |
| `199` | A `date_time` of type `2` (arrive by) or `3` (invariant)    |

Fix the request. Do not retry it as is.

## Errors from api.geolith.app

```json
{
  "error": {
    "code": "secret_key_required",
    "message": "Routing takes a secret key (gc_sk_…) from a server; publishable keys and OAuth tokens are refused.",
    "docs": "https://docs.geolith.app/search/hosted/quotas-and-errors#errors"
  }
}
```

| Status | Code                  | When, and what to do                                                                                                 |
| ------ | --------------------- | -------------------------------------------------------------------------------------------------------------------- |
| 400    | `invalid_request`     | A matrix over 625 cells, or an isochrone over 4 contours. Make the request smaller.                                  |
| 401    | `missing_api_key`     | No key. Send `Authorization: Bearer` or `api_key`.                                                                   |
| 401    | `invalid_api_key`     | Malformed, unknown or revoked key. Check the key in the dashboard.                                                   |
| 403    | `secret_key_required` | A publishable key or an OAuth token. Use a secret key from a server.                                                 |
| 403    | `email_not_verified`  | The account has not verified its email. Verify it at console.geolith.app.                                            |
| 405    | `method_not_allowed`  | Not `GET`, `POST` or `OPTIONS`. Use `POST` with a JSON body.                                                         |
| 413    | `payload_too_large`   | A body over 1 MiB (1,048,576 bytes). Send a shorter trace.                                                           |
| 429    | `rate_limited`        | More routing requests a second than your plan allows. Wait for `Retry-After` and retry.                              |
| 429    | `quota_exceeded`      | The routing allowance has fewer units left than the request needs. Wait for the next month or upgrade; do not retry. |
| 503    | `service_unavailable` | A fault on our side. Wait for `Retry-After` (1 s) and retry.                                                         |

A `quota_exceeded` answer for routing carries `"product": "routing"`:

```json
{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly routing allowance of 10000 units on the Free plan has fewer units left than this request needs (12 left).",
    "product": "routing",
    "reason": "allowance",
    "docs": "https://docs.geolith.app/search/hosted/quotas-and-errors#errors"
  }
}
```

`reason` is `free_daily_ceiling` when all free accounts together reached the day's free routing capacity. It resets at 00:00 UTC. Paid plans are not affected.

A request that needs more units than are left is refused whole. The service never answers part of a matrix.
