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: Hunter
providerId: hunter
created: '2026-05-04'
# Provenance: originally written by the API Evangelist bulk sweep dated 2026-05-04.
# Re-verified 2026-08-13 against the live API reference: every per-endpoint number below was
# read back from https://hunter.io/api-documentation/v2, so the method is upgraded to searched.
method: searched
modified: '2026-08-13'
verified: '2026-08-13'
headers_published: false
headers_note: >-
  Confirmed on 2026-08-13: Hunter documents NO X-RateLimit-* or RateLimit-* response headers.
  The only runtime header any part of the reference names is Retry-After, and only on the
  idempotency_key_in_flight 409 for POST /v2/sequences. An agent has no live budget signal.
retryAfterHeader:
  documented: true
  scope: idempotency_key_in_flight (409) on POST /v2/sequences only
  value: '2'
reconciled: true
tags:
  - Rate Limiting
  - Email
  - Sales Intelligence
description: Hunter applies per-endpoint rate limits enforced per API key, distinct from monthly
  credit quotas. Most endpoints are limited to 15 requests/second and 500 requests/minute, with
  Email Verifier (10/sec, 300/min) and Discover (5/sec, 50/min) operating at lower limits. Throttling
  uses 403 (rate limit reached) and 429 (usage limit / plan exceeded). Credits are tracked separately
  via the Account Information endpoint.
sources:
  - https://hunter.io/api-documentation/v2
  - https://hunter.io/api-documentation/v2#rate-limiting
responseCodes:
  rateLimitReached: 403
  usageLimitReached: 429
limits:
  - name: Domain Search API
    scope: api-key
    metric: requests_per_second
    limit: 15
    timeFrame: second
  - name: Domain Search API (per minute)
    scope: api-key
    metric: requests_per_minute
    limit: 500
    timeFrame: minute
  - name: Email Finder API
    scope: api-key
    metric: requests_per_second
    limit: 15
    timeFrame: second
  - name: Email Finder API (per minute)
    scope: api-key
    metric: requests_per_minute
    limit: 500
    timeFrame: minute
  - name: Email Verifier API
    scope: api-key
    metric: requests_per_second
    limit: 10
    timeFrame: second
  - name: Email Verifier API (per minute)
    scope: api-key
    metric: requests_per_minute
    limit: 300
    timeFrame: minute
  - name: Enrichment endpoints (Email / Company / Combined)
    scope: api-key
    metric: requests_per_second
    limit: 15
    timeFrame: second
  - name: Enrichment endpoints (per minute)
    scope: api-key
    metric: requests_per_minute
    limit: 500
    timeFrame: minute
  - name: Email Count API
    scope: api-key
    metric: requests_per_second
    limit: 15
    timeFrame: second
  - name: Discover API
    scope: api-key
    metric: requests_per_second
    limit: 5
    timeFrame: second
  - name: Discover API (per minute)
    scope: api-key
    metric: requests_per_minute
    limit: 50
    timeFrame: minute
  - name: Free plan monthly credits
    scope: account
    metric: credits_per_month
    limit: 50
    timeFrame: month
  - name: Starter plan monthly credits
    scope: account
    metric: credits_per_month
    limit: 2000
    timeFrame: month
  - name: Growth plan monthly credits
    scope: account
    metric: credits_per_month
    limit: 10000
    timeFrame: month
  - name: Scale plan monthly credits
    scope: account
    metric: credits_per_month
    limit: 25000
    timeFrame: month
policies:
  - name: 403 vs 429 distinction
    description: 403 indicates the per-second/per-minute rate limit was hit and clients should slow
      down. 429 indicates the monthly usage / credit allotment is exhausted and requires a plan
      upgrade or waiting until the next billing cycle.
  - name: Backoff Strategy
    description: Use exponential backoff on 403 responses. Hunter does not document Retry-After or
      X-RateLimit headers; pace clients to stay under documented per-endpoint limits.
  - name: Failed lookups are free
    description: When emails cannot be found or verifications fail, no credits are consumed.
  - name: Account usage tracking
    description: Use the GET /v2/account endpoint to track remaining credits, searches, and verifications
      programmatically rather than relying on response headers.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com