Rate Limiting

Gatelithix enforces rate limits to ensure API stability and fair usage across all merchants. Rate limiting is Redis-backed using the GCRA (Generic Cell Rate Algorithm) with graceful degradation — if Redis is unavailable, requests are allowed through rather than blocked.

Rate Limit Tiers

Your rate limit depends on your account tier. All limits are per rolling 1-minute window.

Tier	Limit	Scope	Description
Global	1,000/min	Per IP	Pre-authentication limit applied to all requests.
Standard	100/min	Per API key	Default tier for all merchants.
Professional	500/min	Per API key	Higher-volume merchants.
Enterprise	2,000/min	Per API key	Custom enterprise accounts.

The global (per-IP) limit applies before authentication. After authentication, your API key’s tier limit applies. Contact support via dashboard.paylithix.com to upgrade your tier.

Response Headers

Every API response includes rate limit headers so you can monitor your usage proactively.

Header	Description	Present
`X-RateLimit-Limit`	Your tier’s request limit per minute.	Always
`X-RateLimit-Remaining`	Requests remaining in the current window.	Always
`Retry-After`	Seconds to wait before retrying.	Only on `429` responses

Example response headers:


HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87

Handling 429 Responses

When you exceed your rate limit, the API returns a 429 Too Many Requests status with a rate_limit_error body.

Error response:


{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "request_id": "req_abc123def456"
  }
}

Important: Always read the Retry-After header and wait the indicated number of seconds. Do not retry immediately — rapid retries will extend your cooldown period.

Backoff Strategy

When rate limited, use exponential backoff with jitter to avoid thundering herd problems.

Formula:


delay = min(base * 2^attempt + random_jitter, max_delay)

Parameter	Recommended Value
Base delay	1 second
Maximum delay	32 seconds
Jitter range	0 — 1 second
Max retries	5 attempts

Best Practices

Monitor X-RateLimit-Remaining proactively. Throttle your requests before hitting the limit rather than reacting to 429 errors.
Batch requests where possible. Combine related operations to reduce total request count.
Cache responses client-side. For read operations (e.g., fetching payment status), cache results to avoid redundant API calls.
Use exponential backoff with jitter. Never retry immediately after a 429. Jitter prevents multiple clients from retrying in lockstep.
Contact support for tier upgrades. If you consistently need more throughput, request a tier upgrade through the dashboard .

Next Steps

Error Codes — See the full rate_limit_error reference.
Authentication — Understand API key types and scopes.
Troubleshooting — Diagnose common integration issues.