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: SmartRecruiters
providerId: smartrecruiters
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:
  - Human Resources
  - Recruiting
  - Applicant Tracking
  - Rate Limiting
description: SmartRecruiters enforces both a per-second request rate and a concurrency cap on its
  API. Standard endpoints allow up to 10 requests per second; job-publication and offer-document
  endpoints are capped at 2 requests per second. Most endpoints permit up to 8 simultaneous
  requests; GET /candidates is restricted to a single concurrent request. Each API credential is
  treated as a separate user for rate-limit accounting. Exceeding either limit returns HTTP 429.
sources:
  - https://developers.smartrecruiters.com/docs/rate-limiting
headers:
  limit: X-RateLimit-Limit
  remaining: X-RateLimit-Remaining
  concurrentLimit: X-RateLimit-Concurrent-Limit
  concurrentRemaining: X-RateLimit-Concurrent-Remaining
responseCodes:
  throttled: 429
limits:
  - name: Standard Endpoints (Request Rate)
    scope: api-credential
    metric: requests_per_second
    limit: 10
    timeFrame: second
    notes: Default rate limit applied to most SmartRecruiters API endpoints.
  - name: Job Publication / Offer Documents (Request Rate)
    scope: api-credential
    metric: requests_per_second
    limit: 2
    timeFrame: second
    notes: Lower per-second cap for job-publication and offer-document endpoints.
  - name: Standard Endpoints (Concurrency)
    scope: api-credential
    metric: concurrent_requests
    limit: 8
    notes: Maximum simultaneous in-flight requests across most endpoints.
  - name: GET /candidates (Concurrency)
    scope: api-credential
    metric: concurrent_requests
    limit: 1
    notes: GET /candidates is restricted to one concurrent request per credential.
policies:
  - name: Per-Credential Accounting
    description: Each API credential is treated as a separate user for rate-limit tracking; sharing
      a credential across services compounds the same caps.
  - name: Distribute Load
    description: SmartRecruiters recommends distributing requests throughout the day rather than
      clustering them at peak times.
  - name: Long Timeouts
    description: Set client request timeouts to a minimum of 128 seconds to avoid spurious retries
      under concurrency pressure.
  - name: Bulk via Reporting API
    description: Use the SmartRecruiters Reporting API for bulk data retrieval; it is optimized for
      high-volume transfers and bypasses some of the standard endpoint constraints.
  - name: Backoff on 429
    description: On HTTP 429, implement exponential backoff with jitter and consult X-RateLimit-*
      headers to reschedule.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com