Launch Front Chat
 Skip to content
Sender.net Logo Sender.net Logo Sender Help Center

API Rate Limits

This guide explains how to monitor, manage, and handle API rate limits when using Sender's REST API.

Prerequisites

  • An active Sender account
  • An API access token generated from Account settings → API access tokens
  • A tool or environment for making HTTP requests (e.g., cURL, Postman, or application code)
  • Familiarity with reading HTTP response headers

Authentication

All Sender API v2 requests use the base URL https://api.sender.net/v2/. Include the Authorization: Bearer header and content-type headers with every request. The API is served only over HTTPS — unencrypted HTTP requests will fail.

bash

curl -X GET \

  "https://api.sender.net/v2/subscribers" \

  -H "Authorization: Bearer YOUR_API_TOKEN" \

  -H "Content-Type: application/json" \

  -H "Accept: application/json"

“`

## Steps to Monitor and Handle API Rate Limits

### Step 1 — Check rate limit headers in API responses

Every API response from Sender includes rate limit headers. After making any request, inspect the response headers for `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. The `X-RateLimit-Limit` header shows the maximum number of requests you can make per minute. The `X-RateLimit-Remaining` header shows how many requests you have left in the current window. Use these values to track your consumption before you hit the limit.

“`

X-RateLimit-Limit: 60

X-RateLimit-Remaining: 45

X-RateLimit-Reset: 2026-03-18T13:02:00Z

“`

### Step 2 — Detect a rate limit response

When you exceed the allowed number of requests per minute, the API returns a `429 Too Many Requests` status code. The response includes a `Retry-After` header that specifies the number of seconds to wait before sending a new request. Stop making requests immediately when you receive a `429` response to avoid further rejections.

“`

HTTP/1.1 429 Too Many Requests

Retry-After: 30

X-RateLimit-Limit: 60

X-RateLimit-Remaining: 0

X-RateLimit-Reset: 2026-03-18T13:02:00Z

Step 3 — Implement exponential backoff retry logic

When a 429 response is returned, read the Retry-After header value and wait at least that many seconds before retrying. If the Retry-After header is not present, use exponential backoff — start with a 1-second delay, then double it on each consecutive 429 response (1s, 2s, 4s, 8s, and so on). Cap the maximum delay at a reasonable ceiling such as 60 seconds. Resume normal request intervals once a successful 2xx response is received.

python

import time

import requests

def make_request_with_backoff(url, headers, max_retries=5):

    delay = 1

    for attempt in range(max_retries):

        response = requests.get(url, headers=headers)

        if response.status_code == 429:

            wait = int(response.headers.get("Retry-After", delay))

            time.sleep(wait)

            delay = min(delay * 2, 60)

        else:

            return response

    return response

Step 4 — Throttle requests proactively using remaining count

Instead of waiting for a 429 response, monitor the X-RateLimit-Remaining header after each request. When the remaining count drops below a threshold (for example, fewer than 5 requests remaining), introduce a delay before the next call. Check the X-RateLimit-Reset header to determine when the window resets, and pause until that time. This approach prevents rate limit errors and keeps your integration running smoothly.

python

remaining = int(response.headers.get("X-RateLimit-Remaining", 1))

if remaining < 5:

    reset_time = response.headers.get("X-RateLimit-Reset")

    # Parse reset_time and sleep until the window resets

    time.sleep(10)

Step 5 — Verify rate limit handling is working

Send a GET request to any endpoint, such as GET https://api.sender.net/v2/subscribers, and confirm the response includes the X-RateLimit-Limit and X-RateLimit-Remaining headers. Verify that X-RateLimit-Remaining decrements with each request. If your backoff logic is in place, simulate rapid requests in a test environment and confirm your code pauses and retries correctly when a 429 status is returned.

Endpoint Reference

GET /v2/subscribers — Returns all subscribers in your account. Supports pagination with ?page, ?limit, ?order, and ?direction query parameters. Use this endpoint to verify rate limit headers are returned in the response.

GET /v2/campaigns — Returns all campaigns in your account. Paginated. Rate limit headers are included in every response, making any list endpoint suitable for testing your rate limit handling.

GET /v2/groups — Returns all subscriber groups. Paginated. Like all Sender API endpoints, responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Error Handling

429 — Too Many Requests — You have exceeded the allowed number of API requests per minute. Read the Retry-After header for the number of seconds to wait before retrying. Implement exponential backoff in your retry logic.

401 — Unauthorized — Your API token is missing, invalid, or expired. Go to Account settings → API access tokens to verify or regenerate your token. Include the Authorization: Bearer YOUR_API_TOKEN header in every request.

400 — Bad Request — The request was malformed or contained invalid data. The response body includes a message field with details about the error. Review the message value and correct the request before retrying.

422 — Bad Request Parameters — One or more required parameters are missing or invalid. The response includes an errors object with per-field details. Check each field listed in the errors object and provide valid values.

5xx — Server Error — An unexpected error occurred on Sender's servers. Do not retry immediately — wait a few seconds and try again. If the error persists, contact support@sender.net.

API Tips

Read headers on every response — Check X-RateLimit-Remaining after every API call, not just when errors occur. This lets you proactively throttle requests before hitting the limit.

Use the Retry-After header — Always prefer the Retry-After value over a hardcoded delay when handling 429 responses. This gives you the exact wait time the server requires.

Batch your operations — Reduce the total number of API calls by using list endpoints with the ?limit parameter to fetch more records per request, rather than making many small requests.

Log rate limit data — Record the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset values from each response. This helps you identify usage patterns and adjust your request frequency over time.

Cap your retry attempts — Set a maximum number of retries (e.g., 5) in your backoff logic. If the limit is still exceeded after the maximum retries, log the failure and alert your team rather than retrying indefinitely.

Common Issues

Requests fail with 429 despite low traffic → Multiple API tokens or parallel processes may be sharing the same rate limit window. Coordinate request timing across all services that use your Sender API credentials.

X-RateLimit-Remaining shows 0 but no 429 returned → The remaining counter may reset between your check and the next request. Always handle a 429 response in your code, even if the remaining count appeared positive on the prior call.

Retry logic causes duplicate operations → Non-idempotent requests (such as POST to create subscribers) can result in duplicate records if retried after a 429. Check whether the resource already exists before retrying create operations.

Rate limit headers are missing from the response → Ensure you are sending requests to https://api.sender.net/v2/ over HTTPS with a valid Authorization: Bearer header. Unauthenticated or malformed requests may not return rate limit headers.

Backoff delay grows too large → If you do not cap your exponential backoff, delays can become unreasonably long. Set a maximum wait time (e.g., 60 seconds) and fall back to that ceiling once the calculated delay exceeds it.

FAQs

Where do I find my API access token?

Go to Account settings → API access tokens in the Sender dashboard. Click Create API token to generate a new one. Copy the token immediately — it may not be displayed again after you navigate away.

What is the rate limit for Sender's API?

Sender enforces a per-minute rate limit on API requests. The exact limit for your account is returned in the X-RateLimit-Limit response header with every API call. Monitor this header to know your current allowance.

What happens if I exceed the API rate limit?

The API returns a 429 Too Many Requests response with a Retry-After header. Wait for the number of seconds specified in Retry-After before retrying. Implement exponential backoff in your code to handle rate limits gracefully.

Are rate limit headers included in every API response?

Yes. Every successful and error response from the Sender API includes the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. Use these to track your usage in real time.

Does the rate limit apply per API token or per account?

The rate limit is tracked per account. If you use multiple API tokens, all tokens share the same rate limit window. Coordinate request timing across all tokens and services to stay within the limit.