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: Mercury
providerId: mercury
created: '2026-05-08'
# Provenance stamped 2026-08-11: this artifact was written by the API Evangelist
# bulk sweep dated 2026-05-08, not harvested from the provider. See roadmap#35.
method: generated
modified: '2026-05-08'
reconciled: false
tags:
  - Banking
  - Fintech
  - Startups
  - Treasury
  - Payments
  - Rate Limiting
  - Throttling
description: >-
  Mercury does not publish a numeric per-second rate-limit ceiling for the public API.
  Excessive calls return HTTP 429 Too Many Requests. The Plus tier caps invoicing API
  invoice-creation at 500 per month; Pro removes that ceiling. Read-and-write tokens
  must be issued from a whitelisted set of source IPs - calls from other IPs return
  401/403 rather than 429.
sources:
  - https://docs.mercury.com/reference/getting-started-with-your-api
  - https://mercury.com/pricing
responseCodes:
  throttled: 429
  unauthorized: 401
  forbidden: 403
limits:
  - name: Per-Token Throttle
    scope: token
    metric: requests
    limit: dynamic
    timeFrame: minute
    notes: >-
      Mercury throttles per-token request rate; numeric ceiling not published. 429 is
      returned when the threshold is exceeded.
  - name: Plus - Invoicing API Quota
    scope: account
    metric: invoice_created
    limit: 500
    timeFrame: month
    notes: Plus tier; invoice creation via API capped at 500 per calendar month.
  - name: Pro - Invoicing API Quota
    scope: account
    metric: invoice_created
    limit: -1
    timeFrame: month
    notes: Pro tier; unlimited invoice creation via API.
  - name: IP Allowlist (Read-Write Tokens)
    scope: token
    metric: source_ip
    limit: allowlisted
    notes: >-
      Read-and-write tokens may only be used from the IP addresses listed when the
      token was issued; other IPs receive 401/403.
policies:
  - name: 429 Throttling
    description: When per-token thresholds are exceeded the API returns 429 Too Many Requests.
  - name: Backoff Strategy
    description: >-
      Implement exponential backoff with jitter on 429 and 5xx responses. Cache
      idempotent reads (account list, statements) to reduce volume.
  - name: IP Allowlisting
    description: >-
      Read-write tokens are bound to a fixed set of source IPs. Rotate the allowlist
      via Settings before deploying calls from new infrastructure.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com