Rate Limiting and Backoff Guide

Rate limiting restricts the number of API calls a user can make to a service within a specific timeframe. This protects against attacks and prevents any user or group from monopolizing bandwidth. EasyPost implements rate limiting not only to safeguard its system but also to protect carrier partners from an overload of requests.

For example, EasyPost enforces a rate limit of five requests per second across Index endpoints; exceeding this limit triggers a 429 HTTP Error, signaling “Too Many Requests.”

• Understanding of HTTP Status Codes, especially 429.
• Knowledge of API calls and error handling.

EasyPost employs a dual-layer rate-limiting strategy designed to maintain system stability and ensure fair usage across all clients.

• The primary Load-based Limiter dynamically protects overall capacity for high-priority operations, such as buying and rating.
• A secondary Fixed Requests Per Second (RPS) limit is applied specifically to high-volume index endpoints to prevent short bursts of read traffic from destabilizing the infrastructure.

Understanding and implementing Retry and Backoff logic is essential to managing fluctuating access limits efficiently.

When a 429 Too Many Requests error occurs, it signals that the request rate has surpassed the allowed threshold. Strategies to manage this include:

• Implementing retry logic to retry the request.
• Temporarily slow down requests to avoid immediate retries.
• Use backoff logic that pairs with retry logic, increasing the wait time between retries with growing intervals until the rate limiting is over.
• Optimize API usage to minimize unnecessary calls to EasyPost.

• Use TLS session resumption and connection pooling to maintain efficient server connections.
• Implement timeout logic to prevent connections from staying open too long. All of EasyPost’s client libraries have configurable timeouts built in.
• Leverage EasyPost’s Batches endpoint for processing multiple shipments, utilizing its asynchronous workflow to handle large volumes efficiently.
• Utilize filtering and smart Pagination to efficiently retrieve objects without overloading the system.

EasyPost’s Python client library, combined with urllib3.util.retry, provides a straightforward method to implement retry and backoff logic:

import requests
from urllib3.util.retry import Retry

retry_strategy = Retry(
    total=3,
    backoff_factor=1,
    status_forcelist=[
        429,
        500,
        502,
        503,
        504,
    ],
    allowed_methods=[
        "DELETE",
        "GET",
    ],
)
requests_session = requests.Session()
requests_http_adapter = requests.adapters.HTTPAdapter(max_retries=retry_strategy)
requests_session.mount(prefix="https://", adapter=requests_http_adapter)