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: Greenhouse
providerId: greenhouse
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-05-05'
reconciled: true
tags:
  - Rate Limiting
  - ATS
  - Recruiting
  - HR
description: Greenhouse Harvest API rate limits use a rolling 10-second window. The actual
  per-window cap is communicated dynamically via the X-RateLimit-Limit response header (it varies
  by approved partner / customer-built integration). When exceeded, the API returns HTTP 429
  with X-RateLimit-Reset (Unix timestamp) and Retry-After (seconds). Other Greenhouse APIs (Job
  Board, Candidate Ingestion, Onboarding, Webhooks) have their own documented limits with the
  same 429 + Retry-After signaling.
sources:
  - https://developers.greenhouse.io/harvest.html
  - https://developers.greenhouse.io/job-board.html
  - https://developers.greenhouse.io/candidate-ingestion.html
headers:
  limit: X-RateLimit-Limit
  remaining: X-RateLimit-Remaining
  reset: X-RateLimit-Reset
  retryAfter: Retry-After
responseCodes:
  throttled: 429
  serviceUnavailable: 503
limits:
  - name: Harvest API — rolling 10-second window
    scope: api-key
    metric: requests_per_period
    limit: 'value of X-RateLimit-Limit header (per 10 seconds)'
    notes: Limit value is set per approved partner / customer integration and exposed in the
      X-RateLimit-Limit header. Default ranges around tens of requests per 10 seconds.
  - name: Job Board API
    scope: api-key
    metric: varies
    limit: 'see developer docs'
    notes: Job Board API has its own published limit; same 429 + Retry-After contract.
  - name: Candidate Ingestion API
    scope: api-key
    metric: varies
    limit: 'see developer docs'
  - name: Onboarding API
    scope: api-key
    metric: varies
    limit: 'see developer docs'
policies:
  - name: Backoff Strategy
    description: When a 429 is received, sleep for the seconds value in Retry-After (or until
      X-RateLimit-Reset Unix timestamp) before retrying. Apply jitter on additional retries.
  - name: Header-driven throttling
    description: Inspect X-RateLimit-Remaining on every successful response to throttle preemptively
      before the next 429.
  - name: Approved-partner allowance
    description: Higher rate-limit allowances are granted to approved Greenhouse partners and
      customer-built integrations.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com