Endpoint Rate Limits

Use this guide to set a traffic limit for an endpoint.

Purpose#

Use this guide to:

• Know the difference between the monthly accepted-event quota and an endpoint rate limit.
• Configure a per-minute limit on one endpoint.
• Read the HTTP responses and the inbound-email responses when the traffic goes above a limit.

How endpoint rate limits operate#

An endpoint rate limit sets the maximum number of HTTP requests or inbound emails that the endpoint accepts in one minute. The limit is separate from the monthly accepted-event quota. A webhook endpoint uses requests for each minute. An email endpoint uses emails for each minute.

Use an endpoint rate limit to:

• Prevent a downstream overload when an endpoint has a wrong configuration, or when a sender uses it incorrectly.
• Apply a burst limit on a high-traffic endpoint.
• Isolate a staging environment with a low-limit endpoint.

When the traffic goes above the limit, PayloadRelay records RATE_LIMITED_ENDPOINT and consumes no monthly quota. The response to the sender depends on the endpoint type:

• An HTTP request receives 429 Too Many Requests with a Retry-After header.
• An inbound email receives a temporary SMTP 451 response. The mail server of the sender controls the length and the frequency of its retries.

Activity counts a rate-limited request as a failure, and the request consumes no monthly quota.

Before you start#

• Make sure that you can edit the endpoint.

Procedure#

1. Configure the rate limit#

1. Open the endpoint edit page.
2. Select the Details tab.
3. Open the Throughput section.
4. Set Requests per minute or Emails per minute to an integer of 1 or more, in the limit of your tier. To use the default of your tier, leave the field blank.
5. Save.

Tier defaults and caps:

Examples:

• 60: 60 requests or emails in one minute on the endpoint.
• 300: 300 requests or emails in one minute on the endpoint.
• Blank: use the default of your tier.

2. Understand burst behavior#

The limit can permit a short burst. The capacity becomes available gradually. It does not reset at a calendar-minute boundary. A sender must use the response, and it must not assume a fixed reset time.

3. Handle rate-limit responses in senders#

A sender must do these actions:

1. Wait for the number of seconds in the Retry-After header before the next request.
2. If the 429 responses continue, use an exponential backoff.
3. Record the rate-limit events.

For an inbound email, the mail server of the sender receives the temporary SMTP response and selects its retry schedule.

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. Select Errors and find the Endpoint Rate Limited (RATE_LIMITED_ENDPOINT) rows.
2. Examine the frequency of the traffic above the limit.
3. If the traffic goes above the limit frequently, do one action or more:
   • Make the limit higher.
   • Collect the requests in batches at the sender.
   • Add a buffer or a rate limit at the sender.

Difference from monthly accepted-event quota#

The monthly quota limits the accepted billable events for the complete organization. An endpoint rate limit controls the HTTP burst throughput or the inbound-email burst throughput on one endpoint.

Expected result#

• PayloadRelay accepts the events that stay in the configured rate.
• An event above the rate receives the response for that endpoint type, and a RATE_LIMITED_ENDPOINT outcome.
• The HTTP Retry-After header gives the wait time before the next request.
• A rate-limited request consumes no monthly quota.

Common issues and fixes#

• Frequent HTTP 429 responses or email SMTP 451 responses: make the rate limit higher, in the limit of your tier. You can also make the sender rate lower.
• An unexpected default limit: a blank value uses the default of your tier. To set a lower limit, enter a value.
• PayloadRelay rejects the value when you save: enter a positive integer that is not higher than the limit of your tier. 0 is invalid.
• The sender ignores Retry-After: add an exponential backoff or a rate-limit function to the sender.

Related guides#

• Endpoint Management
• Billing and Usage
• Observability
• Troubleshooting