Rate Limits

Pace requests across your integration and use customer webhooks instead of frequent polling. Separate request budgets allow batch processing while protecting expensive operations.

Customer API

Each request category has its own budget per organization, with separate sandbox and production budgets. All users and API keys within an organization and environment share the applicable budget. Creating additional credentials does not increase the organization's allowance.

Request category	Sustained allowance	Burst capacity
Reads: lists, status checks and reconciliation	50/second	100
Ordinary writes, including transfer creation	10/second	20
New quote searches	5/second	10
AI document categorization, quality checks and extraction	1/second	3
Report creation and retry	10/minute	2

Up to five new quote searches and two AI document operations can run simultaneously per organization and environment.

Burst capacity allows short spikes above the sustained rate; it is not an additional recurring allowance. Capacity replenishes at the sustained rate. Specialized operations use their own category rather than also consuming the ordinary-write budget. Report reads and downloads use the read budget. Contact Heron to discuss limits for larger integrations.

Production also applies a network limit of approximately 12,000 requests/minute per source IP. Clients sharing an outbound IP share this limit, even when they use different credentials or organizations. These are throttling thresholds, not a guaranteed throughput allocation; distribute requests evenly rather than sending the full allowance at once.

Public payment links

Public payment-link requests are limited to 10 requests per second per source IP. Wallet JSON-RPC requests to /public/payment-links/evm-rpc/... have a separate 100 requests per second per source IP allowance. The production API's per-IP minute limit also applies to these requests. Authenticated organization budgets do not apply to these unauthenticated calls.

These limits apply to requests made to Heron, not to webhook deliveries sent to your receiver.

Handling HTTP 429

When a request is throttled, Heron returns 429 Too Many Requests. Application-level responses use the standard error body and indicate the exhausted budget:

{
  "code": "rate_limit_exceeded",
  "message": "Too many requests"
}

API-generated throttling responses include Retry-After to indicate when to retry. A request blocked before it reaches the API may return a different body and may not include that header. Handle the HTTP status as well as the JSON error code.

• Respect Retry-After when present, then use exponential backoff with jitter for further retries.
• If the header is absent, pause for at least one second before retrying with exponential backoff and jitter. Sustained per-IP throttling may require a longer pause.
• Limit concurrent requests and combine polling where possible.
• For writes requiring Idempotency-Key, retry the same body with the original key. Do not create a new logical payment or export merely because a request was throttled.
• If throttling persists at a steady request rate below these thresholds, contact Heron with the endpoint, timestamp and X-Request-Id when available.

See Error Handling and Customer Webhooks.