Guides

Rate Limiting

Request limits, headers, and handling guidance
View as Markdown

Limits

The Prolifi Public API enforces rate limits per API key. Each API key has an independent rate limit counter.

ParameterDefault
Maximum requests per window1,000
Window duration1 minute

Rate limits are applied per API key, not per merchant. If you use multiple API keys, each key has its own independent limit.

Rate limit headers

Every response includes rate limit headers:

HeaderDescription
X-RateLimit-LimitMaximum number of requests allowed in the current window
X-RateLimit-RemainingNumber of requests remaining in the current window

When the rate limit is exceeded, a 429 response is returned with an additional header:

HeaderDescription
Retry-AfterNumber of seconds to wait before retrying

Exceeded limit response

1{
2  "error": {
3    "type": "rate_limit_error",
4    "message": "Too many requests. Please retry after the rate limit resets."
5  }
6}

Handling rate limits

  • Monitor the X-RateLimit-Remaining header to anticipate when you are approaching the limit.
  • On 429, wait for the Retry-After duration before retrying. Do not retry immediately.
  • Implement exponential backoff for bursts of rate-limited requests.
  • Batch usage events using the POST /events/batch endpoint to reduce the number of individual requests.