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: Yelp
providerId: yelp
created: '2026-05-04'
# Provenance stamped 2026-08-11: this artifact was written by the API Evangelist
# bulk sweep dated 2026-05-04, not harvested from the provider. See roadmap#35.
method: generated
modified: '2026-06-03'
tags:
  - Rate Limiting
  - Quotas
  - Throttling
  - Restaurant
description: >-
  Machine-readable rate limit definitions for the Yelp Fusion API. Captures the
  daily call cap, queries-per-second throttling, response signaling headers, and
  recovery semantics documented at docs.developer.yelp.com. Values reflect Yelp's
  published Places/Fusion rate limiting model.
documentation:
  - https://docs.developer.yelp.com/docs/places-rate-limiting
  - https://docs.developer.yelp.com/docs/graphql-rate-limiting
headers:
  limit: RateLimit-DailyLimit
  remaining: RateLimit-Remaining
  resourceLimit: RateLimit-ResourceDailyLimit
  resourceRemaining: RateLimit-ResourceRemaining
  reset: RateLimit-ResetTime
  retryAfter: Retry-After
responseCodes:
  throttled: 429
  quotaExceeded: 429
  serviceUnavailable: 503
limits:
  - tier: starter
    name: Starter Daily Call Cap
    scope: api-key
    metric: requests_per_day
    limit: 300
    timeFrame: day
    description: >-
      Default daily call cap on the Starter plan, resetting at midnight UTC. The
      window is signaled by the RateLimit-ResetTime ISO 8601 header.
    applies:
      - Yelp Fusion API
  - tier: all
    name: Queries Per Second Throttle
    scope: api-key
    metric: requests_per_second
    limit: null
    timeFrame: second
    description: >-
      Yelp enforces a per-second (QPS) ceiling. Exceeding it returns HTTP 429
      with error code TOO_MANY_REQUESTS_PER_SECOND. The exact QPS ceiling is
      account-specific and not publicly fixed.
    applies:
      - Yelp Fusion API
  - tier: premium
    name: Premium AI Daily Calls
    scope: api-key
    metric: requests_per_day
    limit: 20
    timeFrame: day
    description: >-
      Early-access daily call allotment for the Yelp AI API granted to Premium
      plan subscribers.
    applies:
      - Yelp Fusion API
  - tier: enterprise
    name: Higher Volume (Negotiated)
    scope: contract
    metric: requests_per_month
    limit: -1
    timeFrame: month
    description: >-
      Volumes above 150,000 monthly API calls are negotiated with Yelp sales
      based on actual product usage and traffic.
    applies:
      - Yelp Fusion API
policies:
  - name: Requesting Higher Limits
    description: >-
      Additional daily calls are granted based on actual product usage, typically
      after launch. Contact yelp-api@yelp.com with your Client ID, product
      details, and desired daily request volume.
  - name: Backoff Strategy
    description: >-
      On a 429 response, clients should reduce request rate and implement
      exponential backoff with jitter, honoring Retry-After when present.
  - name: Daily Quota Reset
    description: >-
      The daily call cap resets at midnight UTC. The current window expiry is
      reported as an ISO 8601 timestamp in the RateLimit-ResetTime header.
  - name: Per-Resource Limits
    description: >-
      Some endpoints carry their own caps, signaled via the optional
      RateLimit-ResourceDailyLimit and RateLimit-ResourceRemaining headers.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com