# HARVESTED 2026-08-21, replacing the 2026-05-04 bulk-sweep scaffold.
#
# The scaffold was wrong in both units and shape: it described requests per
# MINUTE and quotas per MONTH across three tiers (free / professional /
# enterprise). The enforced configuration is requests per SECOND and quotas per
# DAY across four (free / starter / pro / business). It also declared five
# response headers -- X-RateLimit-Limit/Remaining/Reset, Retry-After,
# RateLimit-Policy -- none of which the API sent.
#
# Ground truth is the API Gateway usage plan configuration, which agrees exactly
# with https://apis.io/developer/plans. The /developer/rate-limits page claimed
# "there are no per-key quotas in v1"; it contradicted both and was corrected in
# the same pass.
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: APIs.io
providerId: apis-io
created: '2026-05-04'
method: harvested
modified: '2026-08-21'
tags:
- API Aggregation
- API Directory
- API Discovery
- API Indexing
- API Rating
- API Search
- APIs.json
- Search Engine
- Rate Limiting
- Quotas
- Throttling
description: 'Enforced rate limits for the APIs.io API. Metered per API key at the AWS API Gateway usage
  plan bound by the request authorizer: a sustained per-second rate with a short burst ceiling, plus a
  rolling daily quota. Exceeding either answers 429.'
x-source:
- apis-io-aws/lib/apis-io-stack.js (API Gateway usage plans — the enforced values)
- https://apis.io/developer/plans
x-enforced-by: AWS API Gateway usage plans, keyed on x-api-key via the request authorizer
headers:
  policy: RateLimit-Policy
  limit: X-RateLimit-Limit
  window: X-RateLimit-Window
  tier: X-RateLimit-Tier
  observed: '2026-09-11'
  observed_on: GET https://apis.io/api/v1/search?q=weather&limit=1 (anonymous, no key)
  observed_values:
    ratelimit-policy: '"quota";q=500;w=86400, "burst";q=5;w=1'
    x-ratelimit-limit: '500'
    x-ratelimit-window: '86400'
    x-ratelimit-tier: free
  not_sent: [X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After]
  note: >-
    PROBED AND CONFIRMED 2026-09-11. All four headers are now sent on every response, anonymous
    included, and are CORS-exposed. The 2026-08-21 harvest recorded them as declared-but-not-sent;
    they are sent. No remaining-count and no Retry-After, so a caller learns the ceiling and its
    tier from any response but not its distance from the ceiling.
  divergence_from_plans: >-
    The header says the anonymous free quota is 500/day; plans/apis-io-plans-pricing.yml and
    https://apis.io/developer/plans both say 1,000/day. Recorded rather than reconciled — the
    enforced unkeyed number and the published keyed-Free number may legitimately differ.
x-headers-not-sent:
  remaining: X-RateLimit-Remaining and RateLimit-Reset are NOT sent. They describe the state of a counter;
    API Gateway owns that counter and does not expose it to the integration, and there is no per-key usage
    accounting to read. Publishing a remaining value would mean inventing one.
responseCodes:
  throttled: 429
  quotaExceeded: 429
  tierGated: 402
  serviceUnavailable: 503
limits:
- tier: free
  name: Free Tier Rate
  scope: api-key
  metric: requests_per_second
  limit: 5
  burst: 10
  timeFrame: second
  applies:
  - APIs.io API
- tier: free
  name: Free Tier Daily Quota
  scope: api-key
  metric: requests_per_day
  limit: 1000
  timeFrame: day
  applies:
  - APIs.io API
- tier: starter
  name: Starter Tier Rate
  scope: api-key
  metric: requests_per_second
  limit: 20
  burst: 40
  timeFrame: second
  applies:
  - APIs.io API
- tier: starter
  name: Starter Tier Daily Quota
  scope: api-key
  metric: requests_per_day
  limit: 10000
  timeFrame: day
  applies:
  - APIs.io API
- tier: pro
  name: Pro Tier Rate
  scope: api-key
  metric: requests_per_second
  limit: 100
  burst: 200
  timeFrame: second
  applies:
  - APIs.io API
- tier: pro
  name: Pro Tier Daily Quota
  scope: api-key
  metric: requests_per_day
  limit: 100000
  timeFrame: day
  applies:
  - APIs.io API
- tier: business
  name: Business Tier Rate
  scope: api-key
  metric: requests_per_second
  limit: 400
  burst: 800
  timeFrame: second
  applies:
  - APIs.io API
- tier: business
  name: Business Tier Daily Quota
  scope: api-key
  metric: requests_per_day
  limit: 1000000
  timeFrame: day
  applies:
  - APIs.io API
policies:
- name: Backoff Strategy
  description: Clients should implement exponential backoff with jitter on 429. Retry-After is not currently
    sent; back off on the documented policy rather than waiting for it.
- name: Burst Handling
  description: Short bursts above the sustained per-second rate are tolerated up to the burst ceiling
    before throttling engages.
- name: Quota Reset
  description: The quota window is a rolling 24 hours enforced by the gateway, not a calendar month. The
    per-second rate is a token bucket.
- name: Tier Gating
  description: Resources above a caller's tier answer 402, not 403 and not 429 — a payment signal, distinct
    from being rate limited.
maintainers:
- FN: Kin Lane
  email: kin@apievangelist.com