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

// 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)

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.