Skip to content
Docs navigation

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 429 uses nothing. A per-minute 429 does not use a daily request, and a daily-cap 429 does not use the per-minute allowance.
  • A trial key's 403 trial-route-not-allowed on 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-request with the reason in detail. A tool the server does not serve is not a tool result: it is a JSON-RPC error -32602 whose message lists the server's tools and says that search_data returns the get_data call for a question. An ambiguous place name adds candidates, an array of {name} objects to offer the user (names only, no coordinates).
  • A 400 or 404 problem from the API behind a tool reaches you as the API sent it, next_steps included (for example outside-coverage).
  • Every 5xx carries a fixed, generic detail. When the API behind a tool answers 503 or 429 with Retry-After, the problem carries it as retry_after_seconds, as rate-limit-exceeded does.
  • get_data withholds a dataset behind a per-caller flag (civic places today) when it is not enabled for the caller: that element has status: entitlement_required and no features, and a call that reads only withheld datasets returns flag-disabled (403, no next_steps) without calling the API behind it. A second text block tells a model not to retry. The detail says "this caller" rather than "this API key", because an MCP caller may have no key. get_context does not fail in that case: it returns place and ZIP rows without address or POI rows.
  • A tool whose API answers flag-disabled itself returns the same 403 and stop, not a retryable 503.
  • next_steps appears on 401, 402 (trial-ended, payment-required), 403 (trial keys), 404 (outside-coverage, and not-found for a place), 429 (rate-limit-exceeded) and on the 503 a keyless x402 call gets while the payment rail is unavailable.
  • rate-limit-exceeded covers a key over its limit and a keyless x402 wallet over its per-minute limit; it carries retry_after_seconds in place of the Retry-After header and no PaymentRequired, 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 or trial-ended result also carries X-Trial-Calls-Remaining and X-Trial-Expires-At. They are absent on rate-limit-exceeded, trial-route-not-allowed, unauthorized and the service-unavailable answered 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's detail) and error_type (its type) 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.