> ## Documentation Index
> Fetch the complete documentation index at: https://terminal49-codex-update-typescript-sdk-cli-current.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limiting

> Understand Terminal49 API rate limits, HTTP 429 responses, and how to design clients that handle throttling with retries and exponential backoff.

## Overview

Terminal49 API implements rate limiting to ensure fair usage and maintain service quality for all users.

## Rate limit details

* **Limit**: 100 requests per minute per account
* **Scope**: Applied per API key/account
* **Window**: Rolling 60-second window

## Rate limit response

When you exceed the rate limit, the API will return:

**HTTP Status Code**: `429 Too Many Requests`

**Response Headers**:

* `Retry-After`: Number of seconds to wait before making another request

**Response Body**:

```json theme={null}
{
  "errors": [
    {
      "status": "429",
      "title": "Too Many Requests",
      "detail": "Your account has exceeded its API rate limit. Please reduce request frequency or contact support to increase your limit. Consider using webhooks for real-time updates instead of polling."
    }
  ]
}
```

## Best practices

### 1. Use webhooks instead of polling

The most effective way to avoid rate limits is to use **webhooks** for real-time updates instead of repeatedly polling the API:

* Configure webhooks to receive push notifications when shipment data changes
* Eliminates the need for frequent polling
* Provides instant updates without consuming your rate limit
* See the [Webhooks](/api-docs/api-reference/webhooks) section for setup instructions

### 2. Implement exponential backoff

If you receive a `429` response:

1. Check the `Retry-After` header
2. Wait for the specified number of seconds
3. Implement exponential backoff for subsequent failures
4. Don't retry immediately, as this will consume your limit further

### 3. Batch your requests

* Use list endpoints with filtering instead of multiple individual requests
* Leverage the [`include` parameter](/api-docs/in-depth-guides/including-resources) to fetch related resources in a single request
* Cache responses when appropriate to reduce redundant calls

### 4. Monitor your usage

* Track your request patterns
* Identify and optimize high-frequency operations
* Consider spreading requests over time rather than bursting

## Need a higher limit?

If your use case requires a higher rate limit:

1. **Evaluate webhook usage first** - Most polling use cases can be replaced with webhooks
2. **Contact support** at [support@terminal49.com](mailto:support@terminal49.com)
3. **Provide details** about your use case and expected request volume
4. **Our team will work with you** to find an appropriate solution

## Example: handling rate limits

Here's an example of how to properly handle rate limit responses in Python:

```python theme={null}
import time
import requests

def make_request_with_retry(url, headers, max_retries=3):
    """
    Make an API request with automatic retry on rate limit.

    Args:
        url: The API endpoint URL
        headers: Request headers including Authorization
        max_retries: Maximum number of retry attempts

    Returns:
        Response object if successful

    Raises:
        Exception: If max retries exceeded
    """
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 429:
            # Get the retry-after value from header (default to 60 seconds)
            retry_after = int(response.headers.get('Retry-After', 60))
            print(f"Rate limited. Waiting {retry_after} seconds...")
            time.sleep(retry_after)
            continue

        # Return response for any other status code
        return response

    raise Exception("Max retries exceeded")

# Example usage
headers = {
    'Authorization': 'Token YOUR_API_KEY'
}
response = make_request_with_retry(
    'https://api.terminal49.com/v2/shipments',
    headers
)
```

## Tips for high-volume applications

If you're building a high-volume application:

* **Design for webhooks from the start**: Don't rely on polling for data updates
* **Implement request queuing**: Spread your requests evenly across the rate limit window
* **Use pagination efficiently**: Fetch larger pages less frequently rather than small pages frequently
* **Cache aggressively**: Store and reuse data that doesn't change frequently
* **Monitor rate limit headers**: Some APIs provide headers indicating remaining quota (check the Terminal49 response headers)