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: Handwrite IO
providerId: handwrite-io
created: '2026-05-04'
modified: '2026-08-13'
generated: '2026-08-13'
method: probed
source: >-
  https://documentation.handwrite.io/#rate-limiting (published limit) and a live unauthenticated
  GET https://api.handwrite.io/v1/handwriting on 2026-08-13, which returned 401 with the
  rate-limit headers set — confirming the documented numbers on the wire.
docs: https://documentation.handwrite.io/#rate-limiting
tags:
  - Direct Mail
  - Handwritten
  - Marketing
  - Notes
  - Rate Limiting
description: >-
  Handwrite publishes one flat rate limit and returns the three X-RateLimit-* headers on every
  response. This supersedes an API Evangelist scaffold (method: generated, 2026-05-04) that
  invented free/professional/enterprise tiers with 10/100/1000 rpm — Handwrite has no such
  tiers, and the real limit is 60 requests per minute per API key regardless of spend.
limit_count: 1
headers:
  limit: X-RateLimit-Limit
  remaining: X-RateLimit-Remaining
  reset: X-RateLimit-Reset
  retryAfter: null
  policy: null
header_notes: >-
  X-RateLimit-Reset is a Unix epoch second, observed as 1786659140 on the 2026-08-13 probe.
  Handwrite does NOT return Retry-After, and does not implement the RFC 9331 RateLimit /
  RateLimit-Policy fields — an agent must compute its own wait from X-RateLimit-Reset.
responseCodes:
  throttled: 429
  quotaExceeded: 429
  serviceUnavailable: 503
error_on_exhaustion:
  status: 429
  code: rate_limit_exceeded
  documented_meaning: "Too Many Requests -- You're requesting too much! Slow down!"
limits:
  - name: Default API key limit
    scope: api-key
    metric: requests_per_minute
    limit: 60
    burst: null
    timeFrame: minute
    tier: all
    applies:
      - Handwrite IO Handwriting API
      - Handwrite IO Stationery API
      - Handwrite IO Send API
      - Handwrite IO Orders API
    evidence:
      docs: https://documentation.handwrite.io/#rate-limiting
      probed: '2026-08-13'
      observed_headers:
        x-ratelimit-limit: '60'
        x-ratelimit-remaining: '59'
        x-ratelimit-reset: '1786659140'
      probe_url: https://api.handwrite.io/v1/handwriting
      probe_status: 401
      note: >-
        The limit is enforced and the headers are emitted even on an UNAUTHENTICATED request,
        so the counter is bound to the caller before a key is presented. The docs say "each API
        key is rate limited at 60 requests per minute"; no per-account or per-endpoint limit is
        published.
payload_limits:
  - name: Recipients per /send request
    limit: 10
    unit: recipients
    source: https://documentation.handwrite.io/#send-a-letter
  - name: Orders per batch /send request
    limit: 1000
    unit: orders
    source: https://documentation.handwrite.io/#send-a-letter
    note: 'batch mode; one order = 1 message x 1 recipient'
  - name: Message body length
    limit: 320
    unit: characters
    source: https://documentation.handwrite.io/#send-a-letter
policies:
  - name: Backoff Strategy
    description: >-
      Not published by Handwrite. Because no Retry-After is returned, clients should read
      X-RateLimit-Reset (epoch seconds) and sleep until that instant, with jitter.
    published: false
  - name: Burst allowance
    description: No burst ceiling is published; the docs state a flat 60 requests per minute.
    published: false
  - name: Tier-linked limits
    description: >-
      None. Handwrite prices per mailed card, not per API call, and does not vary the rate limit
      by plan. See plans/handwrite-io-plans-pricing.yml.
    published: false
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com