Skip to content
Open Snotel home
API

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

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

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

An invalid parameter looks like this:

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

A range that is too long:

{
  "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 and the API and MCP rules.

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 to tell stale data from a quiet sensor.