Docs navigation
Reference
Weather MCP
Agents
Errors and rate limits
Every error is a JSON problem document with a stable type. For errors
you can act on, a next_steps field tells you or your agent what to do.
This page lists each error type, what it means, and how to respond, plus
how rate limits work (each plan's numbers are on the pricing
page).
Problem documents follow RFC 9457
and use the application/problem+json media type. RFC 9457 obsoletes RFC
7807 with the same wire format.
The Problem shape
Every 4xx or 5xx response body is a JSON object with:
| Field | Type | Required | Meaning |
|---|---|---|---|
type |
string | yes | Stable URI identifying the error class. Switch on this. |
title |
string | yes | Short human-readable label. Safe to display to end users as-is. |
status |
number | yes | HTTP status code. Matches the response line. |
detail |
string | no | Free-form description with request-specific context. May change between releases. |
instance |
string | no | The request path the failure occurred on (e.g. /v1/weather). Pair it with the X-Request-Id response header in support tickets. |
Extension members beyond these five may appear (RFC 9457 §3.2); today
401, 402, 403, 429, and a 404 for a point or place outside
coverage or a place not found carry next_steps (below). Ignore members you do not understand.
reason is an optional extension member: a snake_case
machine code from a bounded list, more specific than type (for example
location_ambiguous on a bad-request). Today it appears on
trial-ended (exhausted or expired) and on MCP tool results.
Branch on type first; use reason only to refine it, and treat a value
you do not know as absent.
Errors the API itself returns are application/problem+json.
Responses that never reach it (an unknown route, a wrong method, a
gateway or throttling error in front of it) can be text/plain or
application/json, so accept both: branch on the HTTP status, then
parse the body as a problem when Content-Type says
application/problem+json.
Example, a key over its per-minute limit (next_steps links other than
the recommended one shortened to their href):
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
RateLimit-Daily-Limit: 1000
RateLimit-Daily-Remaining: 970
RateLimit-Daily-Reset: 21600
RateLimit-Limit: 30
RateLimit-Policy: 30;w=30
RateLimit-Remaining: 0
RateLimit-Reset: 30
Retry-After: 1
{
"type": "https://smarterweather.com/errors/rate-limit-exceeded",
"title": "Too Many Requests",
"status": 429,
"detail": "You have exceeded your API rate limit. Slow your request rate. Retry after the Retry-After / RateLimit-Reset headers.",
"instance": "/v1/weather",
"next_steps": {
"recommended": "upgrade",
"upgrade": {
"href": "https://developers.smarterweather.com/dashboard/billing?utm_campaign=429&utm_medium=problem-json&utm_source=api",
"description": "Raise your rate limit and quota by upgrading the plan on this key's account."
},
"errors": {
"href": "https://developers.smarterweather.com/errors?utm_campaign=429&utm_medium=problem-json&utm_source=api"
},
"pricing": {
"href": "https://developers.smarterweather.com/pricing?utm_campaign=429&utm_medium=problem-json&utm_source=api"
},
"usage": {
"href": "https://developers.smarterweather.com/dashboard/usage?utm_campaign=429&utm_medium=problem-json&utm_source=api"
}
}
}
next_steps: the error tells you what to do
A 401, 402, 403, 429, or a 404 for a point
or place outside coverage or a place not found is where a first integration most often
stalls, so those statuses carry a next_steps
extension member: a map of link relations, each { href, description }
plus optional grant fields, plus recommended naming the one to take
first. When present, if_no_human_present names the relation an
autonomous agent should take if nobody can act on recommended right
now. Relations today: device_flow (401 recommended; also carries
command, client_id, device_authorization_endpoint, token_endpoint,
api_keys_endpoint), trial (on 401 while trial keys are enabled, as
if_no_human_present; carries command, challenge_endpoint,
mint_endpoint), get_key, quickstart, agents,
onboarding_mcp, keyless_x402, key_handling, errors (on 401;
403 recommends get_key), claim (on 402 and trial-route 403),
upgrade, pricing, usage, errors (on 429), and coverage,
errors (on 404; coverage recommended). New relations
may be added; ignore unknown ones. Every href carries
utm_source=api&utm_medium=problem-json&utm_campaign=<status>. Grant
endpoints on device_flow do not get UTM. When a trial key's free value
ends, the response is 402 with next_steps.recommended = claim; the
per-key claim href uses a claim ticket in the URL fragment
(https://developers.smarterweather.com/claim#ticket=<ticket>).
The trial key endpoint (POST /developer/keys/trial) also carries
next_steps on its 400 (recommended = trial, the exact request to send),
429 and 503 (recommended = device_flow).
The keyless 401 (links other than the recommended one shortened to
their href):
HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json
WWW-Authenticate: Bearer realm="api.smarterweather.com"
{
"type": "https://smarterweather.com/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing Authorization header. Pass your API key as 'Authorization: Bearer sw_live_*'.",
"instance": "/v1/weather",
"next_steps": {
"recommended": "device_flow",
"device_flow": {
"href": "https://developers.smarterweather.com/quickstart?utm_campaign=401&utm_medium=problem-json&utm_source=api#device-flow",
"description": "Human present: run the `command` below. It shows the human a verification URL and code, writes SMARTERWEATHER_API_KEY to ./.env (0600, gitignored), and prints only a key prefix. Without Node: device grant at the endpoints below, then POST api_keys_endpoint and write only the response's key field to .env as a SMARTERWEATHER_API_KEY= line (e.g. pipe through jq -r .key). Never print the key or access token.",
"command": "npx -y @smarterweather/mcp-onboarding@latest login",
"client_id": "k2h05BUoTP393zcD",
"device_authorization_endpoint": "https://clerk.smarterweather.com/oauth/device_authorization",
"token_endpoint": "https://clerk.smarterweather.com/oauth/token",
"api_keys_endpoint": "https://api.smarterweather.com/developer/keys"
},
"agents": {
"href": "https://developers.smarterweather.com/llms.txt?utm_campaign=401&utm_medium=problem-json&utm_source=api"
},
"errors": {
"href": "https://developers.smarterweather.com/errors?utm_campaign=401&utm_medium=problem-json&utm_source=api"
},
"get_key": {
"href": "https://developers.smarterweather.com/dashboard/api-keys?utm_campaign=401&utm_medium=problem-json&utm_source=api"
},
"key_handling": {
"href": "https://developers.smarterweather.com/agents?utm_campaign=401&utm_medium=problem-json&utm_source=api#key-handling"
},
"keyless_x402": {
"href": "https://developers.smarterweather.com/agents?utm_campaign=401&utm_medium=problem-json&utm_source=api#x402"
},
"onboarding_mcp": {
"href": "https://developers.smarterweather.com/agents?utm_campaign=401&utm_medium=problem-json&utm_source=api"
},
"quickstart": {
"href": "https://developers.smarterweather.com/quickstart?utm_campaign=401&utm_medium=problem-json&utm_source=api"
}
}
}
When trial keys are enabled, the 401's next_steps also carries if_no_human_present and trial (if_no_human_present names the link an agent with no human present should take):
{
"if_no_human_present": "trial",
"trial": {
"href": "https://developers.smarterweather.com/agents?utm_campaign=401&utm_medium=problem-json&utm_source=api#trial",
"description": "No human present: run the `command` below. It mints a trial key, writes SMARTERWEATHER_API_KEY to ./.env (0600, gitignored), prints only a key prefix and claim link. Without Node: GET challenge_endpoint, solve the SHA-256 proof-of-work, then POST mint_endpoint with the JSON body {\"challenge_token\": \"<from the challenge>\", \"solution\": \"<decimal string>\", \"accept_terms\": <true only once the terms are accepted>, \"client\": {\"name\": \"<your app name>\"}}. Set accept_terms to true only after reading the terms at https://developers.smarterweather.com/legal/terms (newer challenge responses carry them as terms_url, plus a request_example whose accept_terms stays false until you change it). Its api_key field is the bearer; write only that field to .env as a SMARTERWEATHER_API_KEY= line and never print it. Claim into a free account before claim_expires_at.",
"command": "npx -y @smarterweather/mcp-onboarding@latest trial",
"challenge_endpoint": "https://api.smarterweather.com/developer/keys/trial/challenge",
"mint_endpoint": "https://api.smarterweather.com/developer/keys/trial"
}
}
401 and 403 also carry an RFC 6750
WWW-Authenticate: Bearer challenge. A request with no credentials gets
the bare realm (§3.1); otherwise error is invalid_request
(malformed header), invalid_token (unknown, revoked, or expired key),
or insufficient_scope (with scope naming what the route needs), and
error_uri points at this page.
Canonical error type URIs
The type URI prefix is https://smarterweather.com/errors/. These
URIs are stable: new error classes are added over time, but existing
URIs do not change meaning. Compare type as an opaque string --
don't fetch it at runtime. Each one redirects to its row below when a
human does open it.
type (URI suffix) |
HTTP | When | Client reaction |
|---|---|---|---|
bad-request |
400 | Malformed query string, missing required parameter, invalid lat/lon. | Fix the request. Do not retry. |
invalid-request |
400 | A key-API request body is malformed: not JSON, not an object, or a field is missing or has the wrong shape. field names the offending field (for example client.name) when there is one. |
Fix the body. When creating a trial key, start from the challenge's request_example (set accept_terms to true once you accept the terms). Do not retry as-is. |
trial-challenge-invalid |
400 | Trial key creation: the challenge token is invalid, expired, or bound to another IP, or the proof-of-work solution is wrong. | GET a fresh challenge, solve it, and try again. |
terms-not-accepted |
400 | Trial key creation or claim: accept_terms is not true. |
Read the terms (the challenge's terms_url) and send "accept_terms": true. |
unauthorized |
401 | Authorization: Bearer header missing or malformed, or the key is unrecognized, revoked, or expired. |
Follow next_steps.recommended (get a key at the dashboard, or one of the agent paths). Do not retry. Read detail for which case it was. |
trial-ended |
402 | A trial key's free value ended (lifetime call cap spent or key clock expired) while the claim window is still open. Body carries reason (exhausted | expired), claim_expires_at, and next_steps.recommended = claim. |
Follow next_steps.claim (a developer site page with a claim ticket in the URL fragment). Do not treat as a rate limit; a wait will not restore free value. |
payment-required |
402 | MCP only: a keyless call to a paid tool carried no valid x402 payment. The text block also carries the x402 PaymentRequired members (x402Version, accepts, resource), and structuredContent is the bare PaymentRequired; a payment proof the server cannot use gets the same, re-quoted, with the reason in detail. next_steps names the free-key paths. |
Pay one of accepts and retry with the payment, or follow next_steps for a key. Do not retry as-is. |
forbidden |
403 | The key authenticates but its scopes or plan do not grant access to the requested resource. | Surface with an upgrade CTA; next_steps carries the links. |
trial-route-not-allowed |
403 | A trial key authenticated but is not allowed to call this route. next_steps.recommended = claim. |
Claim the key for full API access, or call a route under /v1/weather, /v1/geocode, /v1/alerts, or /v1/catalog (which spends no trial call). A trial key created before /v1/catalog opened to trials gets this error on /v1/catalog: create a new trial key. |
not-found |
404 | The resource does not exist. A place that matches no US location also carries next_steps.coverage. |
Treat as permanent. |
outside-coverage |
404 | The point or place is outside the 50 US states and DC. | Do not retry; follow next_steps.coverage. |
too-many-requests |
429 | A per-minute or per-day limit reached on a surface that is not scoped to a key. | Honor Retry-After; exponential backoff on subsequent hits. |
rate-limit-exceeded |
429 | Your API key exceeded its per-minute or per-day limit. RateLimit-* headers say which; next_steps says how to lift it. |
Honor Retry-After / RateLimit-Reset; follow next_steps.upgrade to raise the limit. |
trial-mint-rate-limited |
429 | Trial key creation: this IP reached its daily cap on new trial keys. Retry-After counts down to UTC midnight. |
Reuse the trial key you already created, or follow next_steps.recommended (device_flow) to get a regular key. |
payload-too-large |
413 | The request body exceeded the endpoint's cap (1 MiB on POST /v1/pois/exposure). |
Split the request. Do not retry as-is. |
conflict |
409 | The write conflicts with current state. On GET /v1/features/{product_id}, reason cursor_stale: the data changed between pages. |
Re-read state and retry once if the conflict is stale; for cursor_stale, page again from the start (suggested_call drops the cursor). |
query-too-slow |
422 | GET /v1/features/{product_id}: the read, a where read included, did not finish within its time budget (reason query_too_slow). |
Narrow it: a smaller area or box, fewer area[feature_ids], a filter, or a lower limit (a where read lists no features, so limit does not narrow it). Do not retry as-is. |
too-many-features |
422 | reason too_many_features: a path crosses more of a product's features than the route reads, or a GET /v1/features/{product_id} where read matches more features than one read takes. |
Send a shorter path, a smaller area or bbox, or a filter. Do not retry as-is. |
where-no-frame |
422 | GET /v1/features/{product_id}: the where product has no frame at the read's at, or a where variable holds none there (the detail names it) (reason where_no_frame). |
Send an at inside the product's served range (GET /v1/catalog/{id}: its horizon and history), or one at which every where variable has a frame. Do not retry as-is. |
flag-disabled |
403 | The endpoint exists but is not enabled for this key. | Treat as not available for this key. |
client-closed-request |
499 | The client closed the connection before the answer was ready (today on GET /v1/agriculture/growing-degree-days). Nobody reads this body; it is in the access log and request metrics, not counted as a server error. |
None: it describes a request you already abandoned. Send it again if you still need the answer. |
internal |
500 | Unhandled server error. Logged with a request id we can look up. | Retry with exponential backoff (max 3); on persistent failure, open a support ticket. |
upstream |
502 | A backing data source returned an error or an undecodable response. | Retry with exponential backoff. Usually transient. |
service-unavailable |
503 | A dependency needed to authorize or serve the request is temporarily unreachable. | Retry with exponential backoff. Never treat as an auth failure. |
trial-mint-unavailable |
503 | Trial key creation: the daily cap on new trial keys across all callers is reached. Retry-After: 3600. |
Follow next_steps.recommended (device_flow) for a regular key, or retry after Retry-After. |
timeout |
504 | The handler deadline elapsed before a downstream response arrived. | Retry with exponential backoff. Usually transient. |
Smarter Weather covers the 50 US states and DC only. The US territories (Puerto Rico, the US Virgin Islands, Guam, the Northern Mariana Islands and American Samoa) and other countries are outside it. Every route that takes a point (lat and lon, zip or location) returns 404 outside-coverage for a point outside the 50 states and DC. /v1/alerts and /v1/observations return it for a bounding box that touches no US domain (CONUS, Alaska, Hawaii); a box that touches one may still include area outside the US. /v1/weather/batch reports it per item as outside_coverage, and /v1/point with points and /v1/series/batch mark such points out_of_domain, as they do a point the check could not reach in time (retry it). If the location lookup is unavailable, the check can briefly fail open. Routes keyed by a station, radar site, forecast office or alert id, and lists that cover the whole country, are not filtered by point, so do not treat an empty result as an all-clear. Do not retry a response with type outside-coverage.
Note that 401 is a single type. The API deliberately does not
distinguish "unknown key" from "revoked key" in the type URI, because
doing so would let an unauthenticated caller probe which key strings
were once valid. Branch on detail for user-facing copy, never for
control flow.
Retry guidance
| Error class | Retry? |
|---|---|
bad-request, unauthorized, forbidden, trial-ended, trial-route-not-allowed, not-found |
No |
payment-required |
Once, with a payment for one of accepts. |
invalid-request, terms-not-accepted |
No; fix the body first. |
trial-challenge-invalid |
Once, with a fresh challenge. |
too-many-requests, rate-limit-exceeded, trial-mint-rate-limited |
After Retry-After (or the RateLimit-Reset window). |
trial-mint-unavailable |
After Retry-After. |
payload-too-large, flag-disabled, query-too-slow, too-many-features, where-no-frame |
No; query-too-slow and too-many-features after narrowing the request (a where read too), where-no-frame with another at. |
conflict |
Once, after re-reading state. |
client-closed-request |
Not applicable; you closed the request. |
internal, upstream, service-unavailable, timeout |
Exponential backoff, max 3 retries. |
Start retries at 250 ms, double the wait each time up to about 2 s, and stop after 3. Spacing retries this way keeps clients from retrying all at once after a short upstream outage.
Rate limits
Limits depend on your plan and apply per key: a per-minute limit and a
daily cap. Both count requests; billing counts credits. Every request
your key makes counts, whatever its status, except requests to the
health, status and deprecations endpoints (/v1/health, /v1/status
and /.well-known/deprecations), which are not rate limited. Two more
exceptions:
- A request rejected with a
429uses nothing. A per-minute429does not use a daily request, and a daily-cap429does not use the per-minute allowance. - A trial key's
403trial-route-not-allowedon a route the API serves gets its per-minute token back. That refund is itself rate-limited per route.
Daily caps reset at 00:00 UTC. The RateLimit-*
headers on each response show what is left. On a 429, wait for
Retry-After before you send the next request. Each plan's numbers are
in the rate limits table
on the pricing page.
Rate-limit headers
A request with a valid key gets these headers (the RateLimit-Daily-* ones only when the key has a daily cap). A response to a request without a valid key, such as a 401, carries none. The examples are a free key after its first call; Retry-After is from a 429:
| Header | Example | Meaning |
|---|---|---|
RateLimit-Limit |
30 |
Burst size: requests you can send back to back. |
RateLimit-Remaining |
29 |
Requests left in the burst right now. |
RateLimit-Reset |
1 |
Seconds until the burst is fully refilled. |
RateLimit-Policy |
30;w=30 |
Burst and refill window as limit;w=seconds. The sustained rate is limit x 60 / w per minute. |
RateLimit-Daily-Limit |
1000 |
Requests per UTC day for this key. |
RateLimit-Daily-Remaining |
999 |
Requests left today. |
RateLimit-Daily-Reset |
21600 |
Seconds until the daily count resets at UTC midnight. |
Retry-After |
1 (from a 429) |
429 only: seconds to wait before the next request. |
On MCP
The Weather MCP (mcp.smarterweather.com) uses
this same model. A failed tools/call is a result with isError: true
whose first text block is one of these Problem objects, serialized as
JSON, with the same type URIs. It carries no structuredContent, with one
exception: on payment-required the text block also carries the x402
PaymentRequired members and structuredContent is the bare
PaymentRequired, the two places x402 clients read it. There is no HTTP
status per tool call, so key on type, then status. Argument, location,
dataset and rate-limit problems add a reason: input_validation,
location_required, location_conflict,
coordinates_incomplete, coordinates_out_of_range, location_not_found,
location_ambiguous, unknown_dataset, rpm_exceeded, daily_exceeded,
wallet_limited, or output_validation on a 500. A payment-required
quote carries none. A re-quote after settlement failed carries
settlement_rejected (the facilitator refused your authorization, for
example a used nonce or low balance) or settlement_failed (the
facilitator or chain failed). After settlement_failed the payment may
still have settled: check your wallet before paying again.
- Argument errors (a value that fails the tool's input schema, or a
precondition such as an ambiguous place name) are
bad-requestwith the reason indetail. A tool the server does not serve is not a tool result: it is a JSON-RPC error-32602whose message lists the server's tools and says thatsearch_datareturns theget_datacall for a question. An ambiguous place name addscandidates, an array of{name}objects to offer the user (names only, no coordinates). - A
400or404problem from the API behind a tool reaches you as the API sent it,next_stepsincluded (for exampleoutside-coverage). - Every
5xxcarries a fixed, genericdetail. When the API behind a tool answers503or429withRetry-After, the problem carries it asretry_after_seconds, asrate-limit-exceededdoes. get_datawithholds a dataset behind a per-caller flag (civic places today) when it is not enabled for the caller: that element hasstatus: entitlement_requiredand no features, and a call that reads only withheld datasets returnsflag-disabled(403, nonext_steps) without calling the API behind it. A second text block tells a model not to retry. Thedetailsays "this caller" rather than "this API key", because an MCP caller may have no key.get_contextdoes not fail in that case: it returns place and ZIP rows without address or POI rows.- A tool whose API answers
flag-disableditself returns the same403and stop, not a retryable503. next_stepsappears on401,402(trial-ended,payment-required),403(trial keys),404(outside-coverage, andnot-foundfor a place),429(rate-limit-exceeded) and on the503a keyless x402 call gets while the payment rail is unavailable.rate-limit-exceededcovers a key over its limit and a keyless x402 wallet over its per-minute limit; it carriesretry_after_secondsin place of theRetry-Afterheader and noPaymentRequired, so x402 clients do not treat it as payable.- A result for a call with a key carries
_meta["smarterweather.dev/budget"]holding the rate-limit header values under their REST names. On a trial key, a served, failed ortrial-endedresult also carriesX-Trial-Calls-RemainingandX-Trial-Expires-At. They are absent onrate-limit-exceeded,trial-route-not-allowed,unauthorizedand theservice-unavailableanswered while trial enforcement is unavailable, and when the key is no longer a trial key. A trial call that fails, including a result that fails the tool's output schema, is not counted against the trial, and the count shows it. An argument error from the tool's input schema carries no budget and is not counted against the trial. - When one of several sources inside a successful result fails, that entry
carries
error(the problem'sdetail) anderror_type(itstype) instead of failing the call.
Retry by the table above.
Including errors in support requests
When you email developers@smarterweather.com,
send the X-Request-Id header value and the instance path from the
body. We use them to find your request.