Usage Rate Limits

To ensure the stability and performance of the Conecto API, rate limiting protects our services from unexpected third-party API usage behavior.

Overview

Rate limiting is a critical mechanism for maintaining API performance and availability. By setting reasonable limits on request frequency, we ensure fair resource allocation across all integrations and prevent system overload.

Why Rate Limiting?

• Service Stability - Prevents individual integrations from overwhelming the API
• Fair Usage - Ensures all partners have equitable access to API resources
• Protection - Guards against accidental infinite loops or misconfigured clients
• Performance - Maintains consistent response times for all users

The Conecto API implements rate limiting on all public endpoints with clear, predictable limits based on endpoint type and request patterns.

Rate Limiting Strategy

Rate Limit Criteria

Rate limits are applied based on three factors:

Window Period

Rate limits are calculated over rolling time windows:

• Default window: 60 minutes (1 hour)
• When limits are reached, you must wait until the window resets
• Each request decrements your remaining quota
• Quota replenishes as time moves forward in the rolling window

Rate Limit Rules

Endpoint-Specific Limits

Different endpoints have different rate limits based on their typical usage patterns and system impact:

Rate Limit Headers

Every API response includes rate limit information in the headers:

Exceeding Rate Limits

Response When Limited

When you exceed the rate limit, the API responds with a 429 Too Many Requests status code:

{
  "status": 429,
  "timestamp": "2023-11-22T10:34:39.646Z",
  "message": "Too Many Requests, exceeded your 500 requests per hour limit.",
  "details": []
}

Handling Rate Limits

When you receive a 429 response, your application should:

1. Stop Making Requests - Immediately cease API calls to that endpoint
2. Read Retry-After Header - Check how long to wait before retrying
3. Implement Backoff - Wait the specified time before making another request
4. Queue Requests - Buffer additional requests until rate limit resets
5. Log the Event - Track rate limit hits for capacity planning

Best Practices

Rate Limit Error Handling

Example Implementation

async function makeApiRequest(url, options) {
  try {
    const response = await fetch(url, options);

    // Check rate limit headers
    const remaining = response.headers.get('X-RateLimit-Remaining');
    const limit = response.headers.get('X-RateLimit-Limit');

    // Warn when approaching limit
    if (remaining && parseInt(remaining) < parseInt(limit) * 0.1) {
      console.warn(`Approaching rate limit: ${remaining}/${limit} remaining`);
    }

    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      const waitSeconds = parseInt(retryAfter) || 60;

      console.error(`Rate limit exceeded. Retrying after ${waitSeconds}s`);

      // Wait and retry
      await new Promise(resolve => setTimeout(resolve, waitSeconds * 1000));
      return makeApiRequest(url, options);
    }

    return response;
  } catch (error) {
    console.error('API request failed:', error);
    throw error;
  }
}

Need Higher Limits?

If your integration requires higher rate limits:

1. Analyze Your Usage - Document your current usage patterns and projected needs
2. Optimize First - Ensure you're using batching, caching, and webhooks effectively
3. Contact Support - Reach out to Shift4 integration support with your use case
4. Provide Metrics - Share data on request volumes, peak usage times, and business requirements

We work with partners to accommodate legitimate high-volume use cases while maintaining service stability for all users.