name: DeBounce Rate Limits
generated: '2026-08-14'
method: searched
source: https://developers.debounce.com/api-concepts/rate-limiting
url: https://developers.debounce.com/api-concepts/rate-limiting
specificationVersion: '0.1'
description: >-
  DeBounce applies CONCURRENCY limits rather than per-minute or per-day request
  quotas for private API keys, and a hard per-IP daily cap for public
  browser keys. The limits are documented clearly — but they are not signalled at
  runtime: a live probe of the API on 2026-08-14 returned no RateLimit-*,
  X-RateLimit-* or Retry-After header on any response, so a client discovers the
  ceiling only by receiving a 429 and must choose its own backoff.

limit_count: 4

limits:
- name: Private API Key — Standard Concurrency
  description: >-
    Regular (private) API keys may have up to 5 concurrent API calls in flight
    for standard validation operations.
  keyType: private
  scope: per-key
  window: concurrent
  limit: 5
  burst: null
  unit: concurrent-requests
  operations:
  - validateEmail
  - checkBulkStatus
  - getBalance
  - getUsage

- name: Private API Key — Data Enrichment Concurrency
  description: >-
    When the data enrichment (append) option is enabled, the concurrent call
    ceiling drops to 2 simultaneous requests.
  keyType: private
  scope: per-key
  window: concurrent
  limit: 2
  burst: null
  unit: concurrent-requests
  operations:
  - validateEmail (append=true)
  - reverseEmailLookup

- name: Public API Key — Daily Per-IP Limit
  description: >-
    Public API keys (prefixed public_) drive the client-side JavaScript widget.
    Each internet IP address is limited to 20 email validations per day, and the
    calling domain must be on the key's approved CORS list.
  keyType: public
  scope: per-ip
  window: 1d
  limit: 20
  burst: null
  unit: requests
  operations:
  - validateEmail (client-side/JavaScript)

- name: Bulk Validation Jobs — Account Concurrency
  description: >-
    Only one active bulk validation job is permitted per account. Additional
    jobs queue automatically and process sequentially.
  keyType: private
  scope: per-account
  window: concurrent
  limit: 1
  burst: null
  unit: active-bulk-jobs
  operations:
  - uploadBulkList

response_headers:
  ratelimit_limit: null
  ratelimit_remaining: null
  ratelimit_reset: null
  retry_after: null
  request_id: null
  observed:
  - date
  - content-type
  - server
  - access-control-allow-origin
  - cf-cache-status
  - report-to
  - vary
  - nel
  - cf-ray
  - alt-svc
  method: probed
  x-evidence:
  - url: https://api.debounce.io/v1/?email=test@example.com
    fetched: '2026-08-14'
    http_status: 401
    note: >-
      Unauthenticated probe. No rate-limit or retry header of any kind was
      returned; the only correlation identifier present is Cloudflare's cf-ray.
  - url: https://disposable.debounce.io/?email=test@mailinator.com
    fetched: '2026-08-14'
    http_status: 200
    note: >-
      Successful unauthenticated call on the free endpoint. Same finding — no
      rate-limit headers.
  note: >-
    The only in-band signal of exhaustion is the 429 status plus a message string
    in the response body. There is no header telling a client how much budget
    remains or when to retry, which is the single largest agent-readiness gap in
    this API.

exhaustion:
  status: 429
  responses:
  - keyType: private
    message: Maximum concurrent calls reached
    body: '{"debounce":{"error":"Maximum concurrent calls reached","code":"0"},"success":"0"}'
  - keyType: public
    message: Authentication Failed - The maximum number of calls per day reached.
    body: '{"debounce":{"error":"Authentication Failed - The maximum number of calls per day reached."},"success":"0"}'
  - scope: bulk
    status: 200
    message: >-
      You have reached the maximum number of API bulk verify requests. Please try
      after the existing request completes.
    note: >-
      Bulk queue saturation is returned inside a 200 with success == "0", NOT as
      a 429. A client branching on status code alone will misread it as success.

upgrade_path:
  documented: true
  mechanism: contact DeBounce support to request upgraded rate limits
  self_serve: false
  note: >-
    The status page monitors a separate "Single Validation API / VIP" endpoint,
    implying a higher-throughput tier exists, but no VIP hostname, limit or price
    is published.

recommendations:
- Use connection pooling or a queue to hold concurrency at or below 5 (2 with append=true)
- Apply client-chosen exponential backoff on 429 — no Retry-After is provided
- Cache validation results to avoid re-charging credits for the same address
- Poll checkBulkStatus before submitting a second bulk job rather than relying on an error
- Always branch on the `success` field, not the HTTP status alone

cross_references:
  conventions: conventions/debounce-conventions.yml
  errors: errors/debounce-problem-types.yml
  plans: plans/debounce-plans-pricing.yml