specification: API Commons Rate Limits
specificationVersion: '0.1'
schema: https://raw.githubusercontent.com/api-evangelist/interface-research/main/schema/api-commons.yml#/$defs/RateLimits
provider: Astronomy API
providerId: astronomy-api
created: '2026-05-04'
modified: '2026-09-04'
generated: '2026-09-04'
method: searched
source: >-
  https://docs.astronomyapi.com/known-issues (Known Issues → "Too many
  requests"), https://docs.astronomyapi.com/endpoints/bodies/positions,
  https://docs.astronomyapi.com/changelog, and the OpenAPI definitions in
  openapi/.
limit_count: 0
description: >-
  Astronomy API ENFORCES rate limiting but PUBLISHES NO NUMBERS. The docs
  confirm the mechanism, the scope and the status code, and state nothing about
  the threshold, the window, the burst allowance or any response header.
enforcement:
  confirmed: true
  quote: >-
    "Due to high resource consumption, you may experience too many requests
    (HTTP 429). Rate limiting is enforced on all consumers based on their IP and
    overall API consumption. Retrying after some time will resolve this error.
    If you require high API usage please send an email to
    contact@astronomyapi.com."
  source: https://docs.astronomyapi.com/known-issues
  since: '2017-08-29'
  since_evidence: 'Changelog 1.1.0 — "Introduced rate limits".'
scopes:
  - scope: per-ip
    documented: true
    limit: null
    window: null
    burst: null
    note: >-
      Stated scope is the caller's IP address AND their "overall API
      consumption" — i.e. two dimensions, neither quantified. Note this is NOT
      scoped to the application key: the credential a developer creates is not
      the throttling subject the docs describe.
  - scope: per-account
    documented: partial
    limit: null
    window: null
    note: >-
      Implied by "overall API consumption" and by the paid-plan sentence on the
      homepage ("high API request rates are available on paid plans"), but no
      per-account figure is published.
headers:
  documented: false
  limit: null
  remaining: null
  reset: null
  retryAfter: null
  policy: null
  note: >-
    NO rate-limit response headers are documented anywhere in the docs or
    declared in any OpenAPI definition, including the v3 draft — which
    otherwise specifies its 400/401/422 responses precisely. An agent has no
    runtime signal: it learns it is throttled only by receiving a 429, and the
    docs tell it to retry "after some time" with no interval to compute.
    This is the single largest runtime-semantics gap on this API.
responseCodes:
  throttled: 429
  throttled_documented: true
  timeout: 504
  timeout_note: >-
    "You may experience endpoint timeouts (HTTP 504) — specifically in the
    studio endpoints. Retrying the request with the same request parameters will
    work." Documented as retry-safe by the provider.
  quotaExceeded: null
  serviceUnavailable: null
limits: []
related_constraints:
  - name: Positions date range ceiling
    value: 366 days
    scope: request
    endpoint: /api/v2/bodies/positions
    source: https://docs.astronomyapi.com/changelog
    evidence: >-
      Changelog 2.14.0 (2023-03-20) — "Date range restriction of a maximum of
      366 days added for positions endpoint."
    note: >-
      A request-shape ceiling rather than a rate limit, recorded here because it
      is the only quantified consumption bound Astronomy API publishes.
  - name: Batch-over-loop guidance
    scope: advisory
    source: https://docs.astronomyapi.com/endpoints/bodies/positions
    evidence: >-
      "Positions API can return position for a single body or all available
      bodies. This is useful if you don't want to make multiple requests for
      each body, and don't want to get throttled by the API request
      limitations."
  - name: RapidAPI shared-key throttling
    scope: third-party marketplace
    source: https://docs.astronomyapi.com/known-issues
    evidence: >-
      "If you're authenticating with Rapid API you may receive a rate limit
      exceeded error. Simply get your own API key from the Astronomy API console
      instead of using the shared Rapid API key."
    note: Callers coming through RapidAPI share a pooled key and are throttled as one consumer.
policies:
  - name: Backoff
    published: partial
    description: >-
      The docs say only "Retrying after some time will resolve this error". No
      Retry-After header, no interval, no backoff algorithm is specified.
  - name: Escalation
    published: true
    description: >-
      Higher throughput is obtained by emailing contact@astronomyapi.com; there
      is no self-serve upgrade path and no published tier ceiling.
note: >-
  This file previously carried five invented per-tier limits (10/100/1000 rpm,
  1,000 and 100,000 requests/month, burst values) and a full set of
  X-RateLimit-* headers, written by the 2026-05-04 bulk sweep and marked
  `method: generated`. Astronomy API publishes none of those numbers and returns
  none of those headers. The scaffold has been replaced with what the provider
  actually documents.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com