# SMKlog Quote API — rate limits, as enforced.
#
# Written by SMKlog from the worker's own configuration; the human page is
# https://smklog.com/developers/rate-limits. Every limit is per client (the
# caller's address and client signature, or the OAuth client when a bearer is
# sent), measured over a sliding hour, and answers HTTP 429 with the Problem
# body {"error":"rate_limited"} when exhausted. No rate-limit response headers
# are sent today.
method: authored
publisher: SMKlog (SMKLOG-2022 LLC)
source: https://smklog.com/developers/rate-limits.yaml
provider: SMKlog
providerId: smklog-com
version: '2026-10-12'
docs: https://smklog.com/developers/rate-limits
limit_count: 3
limits:
  - id: quote-bucket
    scope: per-client
    window: 1 hour
    limit: 80
    applies_to:
      - POST /quote (getParcelQuote)
      - MCP get_parcel_quote
      - A2A get_parcel_quote
      - POST /agent/checkout-session, MCP create_checkout_link and the A2A skill when they price live (no valid quote_id)
    exhaustion_status: 429
    exhaustion_code: rate_limited
    note: >-
      Every quote spends a live carrier rating that costs SMKlog money: one call per shipment, cache on your
      side, never poll. Reusing a quote_id in create_checkout_link spends nothing from this bucket.
  - id: checkout-status-bucket
    scope: per-client
    window: 1 hour
    limit: 60
    applies_to:
      - GET /agent/checkout-session/{session_id} (getCheckoutStatus)
      - MCP get_checkout_status
      - A2A get_checkout_status
    exhaustion_status: 429
    exhaustion_code: rate_limited
    note: Poll minutes apart rather than seconds; nothing moves until the human acts.
  - id: oauth-token-bucket
    scope: per-client
    window: 1 hour
    limit: 20
    applies_to:
      - POST /oauth/token
    exhaustion_status: 429
    exhaustion_code: slow_down
    note: A bearer lives one hour; one token request an hour is the steady state.
exempt:
  - surface: MCP track_parcel
    note: Spends no quote allowance.
  - surface: MCP get_price_index
    note: Spends no quote allowance.
  - surface: GET /status
    note: Liveness probe, cacheable for an hour.
  - surface: discovery documents (/openapi.json, /.well-known/*)
    note: Public, cacheable for an hour.
headers:
  rate_limit: none
  retry_after: none
  note: Buckets are sliding one-hour windows; after a 429, wait and retry later rather than immediately.
higher_tier:
  mechanism: OAuth 2.0 client_credentials bearer (scope quote); a credentialed client gets its own hourly quote bucket at a size agreed at registration.
  registration: manual, by email to info@smklog.com — https://smklog.com/auth.md
  discovery: https://quote-api.smklog.com/.well-known/oauth-authorization-server