Concepts

    Rate limits

    Per-key limits, the headers that report them, and how to back off.

    Limits

    • 120 requests per minute per key (aim for about 60 sustained).
    • 5,000 requests per UTC day per key.
    • GET /v1/whoami returns the limits for your key.
    • Loading history for a new company? Contact support to raise the key's limits for the first upload.

    Headers

    Successful responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset for the per-minute window.

    Over the limit, HelloLedger returns 429 with a Retry-After header in seconds. Wait that long, then retry the same request. Retries are safe because writes are idempotent.

    429 response
    {
  "detail": {
    "status": "fail",
    "reason": "rate_limit_exceeded",
    "limit": "requests_per_minute",
    "reset_at": "2026-10-21T14:03:00+00:00"
  }
}

    Backfills

    For a first import, send records in order (customers, then invoices, then payments) at about one request per second. A few thousand records fit in a day's limit. If you need more for a migration, contact support@helloledger.ai.