Rate Limits

The PostCo API uses rate limiting to ensure reliable performance for all users by preventing any single integration from overwhelming the system. Understanding these limits helps you build resilient integrations that handle high-volume workflows smoothly.

Rate limits are applied per API key and per shop. When you exceed a rate limit, the API returns a 429 Too Many Requests status code. Your integration should handle this gracefully by implementing retry logic with exponential backoff.

Rate limit tiers

The PostCo API enforces rate limits at two levels: per API key and per shop. These limits ensure fair resource allocation while accommodating most integration use cases.

Understanding the two-tier system

Rate limits apply at both the API key level and the shop level simultaneously. Your requests must stay within both limits:

• If you have one API key attempting to make 150 requests per minute, you'll hit the per-key limit at 100 requests, even though you're under the shop limit (500/min)
• If you have 6 API keys each making 90 requests per minute, you'll hit the shop limit (540/min total) even though each key is under its individual limit (100/min)

This system allows multiple integrations while preventing any single integration or shop from consuming excessive resources.

Handling rate limit errors

When you exceed a rate limit, the API returns a 429 Too Many Requests status code with an error message.

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded"
  }
}

Exponential backoff with jitter

The recommended approach for handling 429 errors is exponential backoff with jitter—wait progressively longer between retries, with randomization to prevent thundering herd problems.

async function makeRequestWithRetry(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options)

      if (response.status === 429) {
        // Calculate exponential backoff: 1s, 2s, 4s, 8s, 16s
        const baseDelay = Math.pow(2, attempt) * 1000
        // Add jitter: randomize between -25% and +25% of base delay
        const jitter = baseDelay * 0.25 * (Math.random() * 2 - 1)
        const delay = baseDelay + jitter

        console.log(`Rate limited. Retrying in ${Math.round(delay)}ms...`)
        await new Promise(resolve => setTimeout(resolve, delay))
        continue
      }

      if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${response.statusText}`)
      }

      return await response.json()
    } catch (error) {
      if (attempt === maxRetries - 1) throw error
    }
  }
}

// Usage
const data = await makeRequestWithRetry(
  'https://360.postco.co/api/public/v1/return_orders',
  {
    headers: {
      'Authorization': 'Bearer sk_your_api_key_here'
    }
  }
)

Best practices

Follow these strategies to build integrations that stay within rate limits and handle throttling gracefully.

Common scenarios

High-volume data syncing

If you need to sync large datasets regularly:

1. Batch your operations: Group requests and space them out over the hour
2. Use incremental syncing: Use submitted_at_min to fetch only new/changed data since your last sync
3. Implement checkpointing: Store the last cursor or timestamp to resume if interrupted
4. Schedule during off-peak hours: Reduce contention with other integrations

Real-time monitoring

For integrations that monitor return orders in near-real-time:

1. Poll, don't stream: Check for updates every 1-5 minutes, not every second
2. Use narrow date filters: Query submitted_at_min with recent timestamps to minimize data
3. Implement smart backoff: Reduce polling frequency when no new data appears

Note: Future webhook support will eliminate polling needs for real-time updates. Design your integration to support both polling and webhook-based updates for easier migration when webhooks become available.

Multiple parallel integrations

When running several systems that use the PostCo API:

1. Assign separate API keys: Isolate each integration to track usage independently
2. Coordinate request timing: Stagger requests so they don't all run simultaneously
3. Share rate limit budget: Allocate portions of the 500/min shop limit to each integration
4. Implement circuit breakers: If one integration hits limits repeatedly, pause it to let others operate

Troubleshooting rate limits

Need higher limits?

The current rate limits accommodate most integration patterns, including continuous monitoring, daily batch syncing, and multiple parallel workflows. If you've optimized your integration and still need higher throughput, we're happy to discuss your requirements—contact our support team at [email protected].

When requesting higher limits, please provide:

• Description of your integration and use case
• Current request volume and patterns
• Expected request volume after optimization
• Business justification for higher limits