API Rate Limiting, Throttling & Fair Usage

This page describes the default API usage limits, throttling behavior, HTTP 429 handling, and fair usage requirements for Lemonway API partners.

Why we enforce limits

Rate limits and throttling help us maintain:

• Platform stability
• Fair access across partners
• Predictable performance during traffic peaks
• Protection against abusive, accidental, or misconfigured traffic
• Reliable processing of payment and payout operations

How limits are applied

Limits may be applied at one or more of the following levels:

• Partner
• API credential
• Endpoint family
• IP address or source
• Environment, such as Sandbox or Production

The API enforces both:

• Sustained limits, which control the average request rate over time
• Burst limits, which control short periods of elevated traffic
• Concurrency limits, which control the number of requests being processed at the same time

Where multiple limits apply, the most restrictive applicable limit takes precedence.

Default production limits

The following limits apply by default in the Production environment:

The burst limit is intended for short-lived traffic peaks. Partners must return to the sustained rate after the burst period.

These limits are aggregated across the partner's API credentials unless Lemonway has agreed otherwise in writing. Using multiple credentials, IP addresses, or sources to bypass a limit is not permitted.

Default Sandbox limits

The following lower limits apply in the Sandbox environment:

Sandbox traffic may also be subject to additional restrictions during periods of high shared usage.

Endpoint-specific protection

Some endpoint families have additional limits because they require more processing or involve financial state changes.

Endpoint-specific limits apply in addition to the global partner limits.

For report generation and other long-running operations, partners should use asynchronous exports and retrieve results only when notified or when the export is ready. Aggressive polling is not permitted.

What happens when limits are exceeded

When a limit is exceeded, the API may:

• Return 429 Too Many Requests
• Include a Retry-After response header
• Temporarily reduce the accepted request rate
• Reduce the permitted concurrency
• Apply additional protective restrictions in severe or repeated cases

A response below the sustained average does not guarantee that a request will be accepted. A request may still be throttled because of:

• A short-term burst
• Endpoint-specific protection
• Concurrent in-flight requests
• Traffic from another credential belonging to the same partner
• Temporary platform protection

Rate limit response headers

Where applicable, responses include the following headers:

If the gateway uses different header names, the exact names and semantics used in Production must be documented and kept consistent.

Partners must not assume that limits are unlimited when these headers are absent. Clients should remain capable of handling throttling at any time.

Required behavior on HTTP 429

When the API returns 429 Too Many Requests, clients must:

1. Stop immediate retries.
2. Wait for the duration specified by Retry-After, when present.
3. Retry using exponential backoff and jitter.
4. Reduce concurrency and request frequency.
5. Resume normal traffic gradually once requests are accepted consistently.

Retry standard

Unless otherwise agreed, clients should use the following retry policy:

• Maximum attempts: 4 total attempts, including the initial request
• Fallback backoff: 1 second, 2 seconds, then 4 seconds
• Maximum fallback delay: 30 seconds
• Jitter: Random variation of approximately ±25%
• Server-provided delay: Retry-After takes precedence over the fallback backoff
• Circuit breaker: Pause requests after repeated throttling or retry failures

Clients must also place a limit on the total time spent retrying. A request that cannot be completed within the client-defined retry window should be failed or deferred for later processing.

Do not retry blindly

The following responses should not be retried automatically without correcting the underlying issue:

Write operations must use idempotency keys so that a retry cannot unintentionally create duplicate payments, payouts, or other financial operations.

Fair usage requirements

Partners must:

• Avoid aggressive polling when webhooks or events are available
• Deduplicate requests where possible
• Use idempotency keys for write operations
• Use queues and controlled throughput for batch processing
• Respect both global and endpoint-specific limits
• Monitor request, error, retry, and throttling rates
• Alert on abnormal traffic spikes and retry storms
• Stop or slow traffic when repeated 429 responses occur
• Avoid using multiple credentials or IP addresses to circumvent limits
• Prefer asynchronous exports for reports and long-running operations

A partner's traffic should be designed so that normal operations remain below the sustained limit. The burst allowance should be reserved for short-lived and exceptional peaks.

Temporary traffic increases

If you expect an unusual increase in traffic, contact Lemonway in advance.

Examples include:

• Marketing campaigns
• Large payment batches
• Migration activity
• Reconciliation jobs
• Seasonal peaks
• Major partner or merchant launches

The request should include:

• Expected sustained rate in requests per second and per minute
• Expected peak burst rate
• Expected duration
• Impacted endpoint families
• Number of credentials and sources involved
• Retry and backoff strategy
• Technical owner and emergency contact

Requests are reviewed case by case. An approved temporary increase does not remove the requirement to implement safe throttling, retries, idempotency, and monitoring.

---

Policy updates

Lemonway may adjust limits and protective controls to maintain platform stability, reliability, and security.

Material changes will be communicated through the API changelog or other applicable partner communication channels.

---

FAQ

Are these limits shared across all endpoints?

Some limits are global per partner. Others are specific to an endpoint family. Both types may apply to the same request.

Can I request higher limits?

Yes. Higher limits may be considered when the partner provides a justified business need and demonstrates appropriate queueing, retry, idempotency, monitoring, and traffic-control mechanisms.

Why did I receive a 429 response even though my average rate was below the limit?

You may have exceeded:

• The short-term burst limit
• An endpoint-specific limit
• The concurrent request limit
• A limit aggregated across another credential or source belonging to the same partner

Can I send 10 requests per second continuously?

No. The burst rate is intended for short-lived peaks only. Continuous traffic must remain within the sustained limit of 300 requests per minute per partner in Production.

Should I retry a failed payment or payout?

Only when the response is retryable and the operation uses an idempotency key. Do not blindly retry financial write operations, because the original request may have been accepted even if the client did not receive the response.