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