# Errors

> Handle API errors: the one error shape every endpoint returns, each code with its HTTP status, and what to do about it.

API errors share one shape so that clients and agents can handle them the same way everywhere.

## The error body

```json
{
  "error": {
    "code": "station_not_found",
    "message": "There is no station 999:ID:SNTL. Search the station list by name or state, or find the stations nearest a point, and use the id (triplet) it gives.",
    "details": { "station": "999:ID:SNTL" }
  }
}
```

`code` is stable and meant for programs. `message` is written for a person or an agent and may be reworded. `details` is optional and holds machine-readable specifics, such as which parameters were wrong or what a limit is.

## Codes and statuses

| Status | `code`                | Meaning and what to do                                                                                           |
| ------ | --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| 400    | `invalid_parameter`   | A parameter is missing or malformed. `details.parameters` names them. Fix the request; retrying will not help.   |
| 404    | `station_not_found`   | The triplet is well formed but not in the catalog. Search for the station.                                       |
| 404    | `resort_not_found`    | The slug is well formed but no resort has ever had it. List resorts by name or region and use the slug given.    |
| 404    | `element_unavailable` | The station does not report a requested element at that duration. `details` names them; read the station first.  |
| 404    | `not_found`           | No endpoint at that path under `/api/v1`. See the OpenAPI document.                                              |
| 422    | `range_too_large`     | The range is longer than one request returns. `details` has the limit. Ask for a shorter range and page through. |
| 429    | `rate_limited`        | Too many requests from one client in a short time. Wait as long as `Retry-After` says, then slow down.           |
| 500    | `internal_error`      | Something went wrong on our side. The message is generic by design. Retry shortly.                               |

An invalid parameter looks like this:

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "limit: Too big: expected number to be <=500",
    "details": { "parameters": ["limit"] }
  }
}
```

A range that is too long:

```json
{
  "error": {
    "code": "range_too_large",
    "message": "2193 days of DAILY data is more than one request returns (at most 366). Ask for 366 days or fewer at a time and page through the range.",
    "details": { "maxDays": 366, "requestedDays": 2193, "duration": "DAILY" }
  }
}
```

## Rate limits

The API and the MCP server are free and keyless, so each client (by IP address) gets a fair share: separate per-minute limits for `/api/v1` and `/mcp`, generous for interactive and agent use, and adjusted as real traffic shows what is needed. A client over its limit gets `429`. The limit is enforced at the edge before a request reaches the API, so a `429` may come without the error body above: rely on the status, and on `Retry-After` when it is present, not on `code`. Wait, then retry more slowly; looping on a `429` only extends it. Using the API commercially or above the free limits needs a plan: see [Pricing](/pricing) and the [API and MCP rules](/terms#5).

## Retrying and caching

Retry `500` after a pause, and `429` after the wait it asks for. Every other `4xx` describes the request, so the same request will fail the same way. Client errors may be cached briefly by a shared cache, and `500` responses are never cached.

Errors never include database or source text, credentials, or stack traces; details of a failure are logged on our side.

## Stale data is not an error

A station whose feed has stopped is answered normally. Check `freshness` on [latest conditions](https://opensnotel.com/docs/api/observations.md#reading-freshness) to tell stale data from a quiet sensor.

## Next

- [Overview](https://opensnotel.com/docs/api.md): Use the REST API at /api/v1: every endpoint, the conventions all responses follow (UTC times, null for missing, the source's units and flags), request bounds and caching.

Canonical page: https://opensnotel.com/docs/api/errors
