Errors and limits

Errors

Errors are JSON in the problem details format, with a stable code and a request_id. Include the request_id if you contact support.

{
  "type": "urn:atmosphere:problem:outside_coverage",
  "status": 404,
  "code": "outside_coverage",
  "title": "Outside GFS time coverage",
  "request_id": "5f0c3e9b2a7d4c1e8f6a0b9d3c2e1f07"
}

Status	Code	Meaning
400	invalid_request	The body or one of its fields is invalid.
401	unauthorized	The API key is missing, revoked or wrong.
404	outside_coverage	No model data covers that time.
409	profile_out_of_range	A height is outside the available column; see coverage.
429	rate_limited	A usage limit was reached; see Retry-After.
502	upstream_unavailable	NOAA’s data couldn’t be retrieved or was incomplete.
503	source_busy, service_unavailable	Temporarily busy or unavailable; see Retry-After.

Limits

Every account has two kinds of limit. They are shared by all of its keys.

• Requests: 5 per second and 60 per minute. Every profile request counts, including cached ones.
• Data fetches: 100 per day (UTC). Only requests that have to download new model data count; see the X-Cache header.

The current values are also published at /v1/atmosphere/capabilities, and your remaining daily allowance at /v1/atmosphere/usage. They may change during the beta.

Retrying

429 and 503 responses include a Retry-After header with the number of seconds to wait. Wait at least that long, and add some random delay if you retry in a loop.

Don’t retry 400, 401, 404 or 409 without changing the request; the answer won’t change. A 502 usually means NOAA’s servers are having trouble, and a later retry often works.

A request can time out on your side after the server has already done the work, so limit retries to one or two.