> ## Documentation Index
> Fetch the complete documentation index at: https://docs.packageretriever.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limits

> Published rate limits for every API endpoint. No surprises.

# Rate Limits

Every endpoint has a published rate limit. You will never discover a limit by hitting a 429 in production — they're all documented here.

## Limits by endpoint

| Endpoint                  | Method | Limit            |
| ------------------------- | ------ | ---------------- |
| `/v1/rates`               | POST   | 100 requests/min |
| `/v1/addresses/validate`  | POST   | 200 requests/min |
| `/v1/labels`              | POST   | 60 requests/min  |
| `/v1/labels/{id}`         | GET    | 300 requests/min |
| `/v1/labels/{id}`         | DELETE | 30 requests/min  |
| `/v1/trackers`            | POST   | 200 requests/min |
| `/v1/trackers/{id}`       | GET    | 300 requests/min |
| `/v1/carrier-accounts`    | GET    | 300 requests/min |
| `/v1/batches`             | POST   | 10 requests/min  |
| `/v1/batches/{id}`        | GET    | 300 requests/min |
| `/v1/batches/{id}/buy`    | POST   | 10 requests/min  |
| `/v1/wallet`              | GET    | 300 requests/min |
| `/v1/webhooks/deliveries` | GET    | 300 requests/min |

Limits are per API key.

## Response headers

Every response includes rate limit information:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1716825600
```

* `X-RateLimit-Limit` — your limit for this endpoint
* `X-RateLimit-Remaining` — requests remaining in the current window
* `X-RateLimit-Reset` — Unix timestamp when the window resets

## When you hit a limit

```json theme={null}
// 429 Too Many Requests
{
  "error": {
    "code": "AUTH.RATE_LIMIT.EXCEEDED",
    "message": "Rate limit exceeded for POST /v1/labels. Limit: 60 requests per minute.",
    "suggestion": "Wait 32 seconds before retrying. See rate limit headers for current usage.",
    "docs_url": "https://docs.packageretriever.com/guides/rate-limits",
    "request_id": "req_r4j2k9m5"
  }
}
```

The response includes a `Retry-After` header (in seconds).

## Retry logic (recommended)

```typescript theme={null}
async function apiCallWithRetry(fn: () => Promise<Response>, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fn();

    if (response.status !== 429) return response;

    const retryAfter = parseInt(response.headers.get('Retry-After') ?? '60');
    const jitter = Math.random() * 1000; // Add 0-1s jitter
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000 + jitter));
  }

  throw new Error('Rate limit exceeded after maximum retries');
}
```

## Need higher limits?

Contact us via Intercom in the dashboard. Higher limits are available for high-volume integrations at no additional cost.