# Responses and errors

> Response shape, the geocoding block, and status codes.

Every endpoint returns a GeoJSON `FeatureCollection` in the Pelias shape.

## The `geocoding` block

| Field | Meaning |
| --- | --- |
| `version` | Pelias response version. |
| `attribution` | URL of the data attribution page. |
| `engine` | `name` and `version` of the server. |
| `query` | The parsed request: `text` or `fields`, `size`, and `ranking`. Reverse returns its point and radius instead. |
| `query.ranking` | `importance` (text score plus importance) or `importance+distance` (with a focus point). |
| `errors` | Present only on errors: human-readable messages. |

## Feature properties

Each feature has `id`, `gid`, `layer`, `source`, `name`, `label` and `importance`, plus the fields that are known for that place: `street`, `postalcode`, `locality`, `county`, `region`, `country` and `country_code`. Text searches add `confidence`. Results near a focus point, and all reverse results, add `distance` in kilometres. The collection also has a `bbox` of all features.

## Status codes

| Status | When |
| --- | --- |
| `200` | Success, including an empty result. |
| `400` | A parameter is missing or invalid. |
| `500` | The `.glx` file cannot be read. The error message is `the search index is unavailable`. |

## Validation errors

```bash
curl 'http://localhost:4000/v1/search'
# HTTP 400
```

```json
{
  "features": [],
  "geocoding": {
    "errors": [
      "missing param 'text'"
    ]
  },
  "type": "FeatureCollection"
}
```

```bash
curl 'http://localhost:4000/v1/search?text=pune&size=0'
# HTTP 400
```

```json
{
  "features": [],
  "geocoding": {
    "errors": [
      "size must be between 1 and 40"
    ]
  },
  "type": "FeatureCollection"
}
```

```bash
curl 'http://localhost:4000/v1/search?text=cafe&layers=planet'
# HTTP 400
```

```json
{
  "features": [],
  "geocoding": {
    "errors": [
      "unknown layer 'planet'; supported: venue, address, street, locality, county, region, country"
    ]
  },
  "type": "FeatureCollection"
}
```

```bash
curl 'http://localhost:4000/v1/search?text=cafe&focus.point.lat=18'
# HTTP 400
```

```json
{
  "features": [],
  "geocoding": {
    "errors": [
      "focus.point.lat and focus.point.lon must be set together"
    ]
  },
  "type": "FeatureCollection"
}
```