Endpoint Rate Limits

Use this guide to configure per-endpoint rate limits for traffic control.

Purpose

This guide helps you:

• Understand the difference between monthly quota and per-endpoint rate limits.
• Configure a requests-per-minute cap on an individual endpoint.
• Interpret 429 responses and Retry-After headers when limits are exceeded.

How endpoint rate limits work

Per-endpoint rate limits cap the number of requests an endpoint can accept per minute, independent of your monthly quota.

This is useful for:

• Preventing downstream overload when an endpoint is misconfigured or abused.
• Enforcing burst limits on high-traffic endpoints.
• Staging environment isolation (deploy a low-limit endpoint to catch runaway loops).

When the limit is exceeded, PayloadRelay returns:

• HTTP 429 Too Many Requests
• Retry-After: <seconds> header indicating when the next token will be available
• Outcome logged as RATE_LIMITED_ENDPOINT

Rate-limited requests count as failures in activity logs and do not consume monthly quota.

Prerequisites and permissions

• Endpoint edit access.

Step-by-step workflow

1. Configure the rate limit

1. Open the endpoint edit page.
2. Navigate to the Details tab.
3. Scroll to the Throughput section.
4. Set Max requests per minute to an integer ≥ 1 within your tier cap, or leave blank to use your tier default.
5. Save.

Tier defaults and caps:

Examples:

• 60 — 60 requests per minute (1 per second average)
• 300 — 300 requests per minute (5 per second average)
• Blank — inherit your tier default

2. Understand token bucket semantics

The rate limit uses a token bucket algorithm:

• Bucket capacity = configured rate (e.g., 60 tokens for a 60 req/min limit).
• Tokens replenish at rate / 60 per second (e.g., 1 token/sec for 60 req/min).
• Each request consumes 1 token.
• When the bucket is empty, requests are rejected with 429.

This allows short bursts (up to the full bucket capacity) while enforcing the average rate over time.

3. Handle 429 responses in senders

Senders should:

1. Respect the Retry-After header (seconds until the next token is available).
2. Exponentially back off if repeated 429 responses occur.
3. Log rate-limit events for visibility.

Example (Node.js):

async function sendToEndpoint(url, payload) {
  const response = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
  });

  if (response.status === 429) {
    const retryAfter = response.headers.get('Retry-After');
    console.log(`Rate limited. Retry after ${retryAfter} seconds.`);
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return sendToEndpoint(url, payload); // retry
  }

  return response;
}

4. Monitor rate-limited requests

In Request activity:

1. Filter by outcome RATE_LIMITED_ENDPOINT.
2. Check the frequency of rate-limited requests.
3. If rate limits are hit frequently, consider:
   • Increasing the limit.
   • Batching requests at the sender.
   • Adding sender-side buffering or rate limiting.

Difference from monthly quota

Monthly quota limits your total monthly usage. Per-endpoint rate limits control burst throughput on individual endpoints.

Expected result and verification checks

• Requests within the configured rate are accepted (ACCEPTED outcome).
• Requests exceeding the rate are rejected with 429 and RATE_LIMITED_ENDPOINT outcome.
• The Retry-After header provides a hint for when to retry.
• Rate-limited requests do not consume monthly quota.

Common issues and fixes

• Frequent 429s: Increase the rate limit within your tier cap or optimize sender batching/rate limiting.
• Unexpected default limit: Blank values inherit your tier default. Set an explicit value if you need a lower cap.
• Value rejected when saving: Use a positive integer no higher than your tier cap; 0 is invalid.
• Sender ignores Retry-After: Implement exponential backoff or rate-limit handling in the sender.

Related guides

• Endpoint Management
• Billing and Usage
• Observability
• Troubleshooting