Rate Limits

Overview

PaymentHooks enforces rate limits on all API endpoints to ensure platform stability, prevent abuse, and guarantee fair resource allocation across all tenants. Rate limits are applied per API key and vary by subscription plan. When a limit is exceeded, the API responds with HTTP 429 Too Many Requests and includes headers that indicate when you can retry.

Rate limit tiers by plan

Each subscription plan has distinct rate limit thresholds. Limits are evaluated across three rolling windows: per minute, per hour, and per day.

Rate limit headers

Every API response includes rate limit headers so your integration can track consumption in real time and pre-emptively throttle before hitting the limit.

429 response format

When a rate limit is exceeded, the API returns an HTTP 429 status with the standard error envelope. The Retry-After header indicates the number of seconds to wait before retrying.

{
"data": null,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "API rate limit exceeded. Retry after 42 seconds."
}
}

Endpoint-specific limits

Certain security-sensitive and resource-intensive endpoints enforce stricter limits independent of your plan tier. These limits are scoped per IP address or per session.

Best practices

Follow these recommendations to minimise the chance of hitting rate limits and to handle throttled responses gracefully.

• Implement exponential backoff. When retrying after a 429, increase the delay exponentially (e.g. 1s, 2s, 4s, 8s) with jitter to avoid thundering herd effects.
• Cache responses where possible. Store frequently requested data locally to reduce redundant API calls. Use ETag and If-None-Match headers for conditional requests.
• Use webhooks instead of polling. Subscribe to webhook events for real-time notifications rather than polling endpoints at fixed intervals.
• Read the Retry-After header before retrying. The Retry-After header provides the exact number of seconds to wait. Always honour this value rather than using a fixed delay.
• SDK handles rate limits automatically. The PaymentHooks SDK automatically retries on 429 responses up to 3 times, respecting the Retry-After delay between attempts.

SDK rate limit handling

The official PaymentHooks SDK handles rate limit responses transparently. When the API returns a 429, the SDK reads the Retry-After header and automatically retries the request up to three times with the appropriate delay.

import PaymentHooks from '@paymenthooks/sdk';
const ph = new PaymentHooks('phk_live_...');
// SDK automatically retries on 429 with Retry-After delay
const payment = await ph.payments.create({ ... });