Skip to main content

Documentation Index

Fetch the complete documentation index at: https://packageretriever.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
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

EndpointMethodLimit
/v1/ratesPOST100 requests/min
/v1/addresses/validatePOST200 requests/min
/v1/labelsPOST60 requests/min
/v1/labels/{id}GET300 requests/min
/v1/labels/{id}DELETE30 requests/min
/v1/trackersPOST200 requests/min
/v1/trackers/{id}GET300 requests/min
/v1/carrier-accountsGET300 requests/min
/v1/batchesPOST10 requests/min
/v1/batches/{id}GET300 requests/min
/v1/batches/{id}/buyPOST10 requests/min
/v1/walletGET300 requests/min
/v1/webhooks/deliveriesGET300 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). 
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.